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NAME 

intro — introduction to commands 
DESCRIPTION 

™ S nSt”.ht£dS g r“ y “ C “ SSib " a,PhabeliC ° rter - Cmai ” disa " cti0ns of 

(1) Commands of general utility. 

(1C) Commands for communication with other systems. 

(1G) Commands used primarily for graphics and computer-aided design. 

SEE ALSO 

Section 6 in this manual for computer games. 

Section 7 in this manual for descriptions of publicly available files and macro packages for docu- 
ment preparation. 6 

Section 8 in this manual for system administration procedures, system maintenance and operation 
commands, plus descriptions of network services daemons and servers. 

• Getting Started With UNIX: Beginner' s Guide 

• Setting Up Your UNIX Environment: Beginner’s Guide 

• Windows and Window-Based Tools: Be ginner’ s Guide 

° U sing the Network: Beginner’ s Guide 

DIAGNOSTICS 


Upon termination each command returns two bytes of status, one supplied by the system giving the cause 
for termination, and (in the case of ‘normal’ termination) one supplied by the program, see wait and 
exit W- The former byte is 0 for normal termination, the latter is customarily 0 for successful execution, 
nonzero to indicate troubles such as erroneous parameters, bad or inaccessible data, or other inability to 
cope with the task at hand. It is called variously ‘exit code’, ‘exit status’ or ‘return code’, and is described 
only where special conventions are involved. 
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NAME 

adb - debugger 
SYNOPSIS 

adb [ -w ] [ -k ] [ -I dir ] [ objfil [ corfil ] ] 

DESCRIPTION 

Adb is an interactive, general purpose debugger. It examines files and provides a controlled environment 
for the execution of UNIX programs. 

Objfil is normally an executable program file, preferably containing a symbol table. If the file does not con- 
tain a symbol table, it can still be examined, but the symbolic features of adb cannot be used. The default 
for objfil is a.out. Corfil is assumed to be a core image file produced after executing objfil. The default for 
corfil is core. 

OPTIONS 

-w Create both objfil and corfil if necessary and open them for reading and writing so that files can be 
modified using adb. 

-k Do UNIX kernel memory mapping; should be used when core is a UNIX crash dump or 
Idev/mem. 

—I specifies a directory where files to be read with $< or $« (see below) will be sought; the default 
is lusr/lib/adb. 

USAGE 

Refer to Adb in Pro gram Debugging Tools for the Sun Workstation . 

FILES 

a.out 

core 

SEE ALSO 

cc(l), dbx(l), ptrace(2), a.out(5), core(5) 

Using adb to debug the UNIX kernel in the Sun System Internals Guide. 

DIAGNOSTICS 

‘Adb’ when there is no current command or format. Comments about inaccessible files, syntax errors, 
abnormal termination of commands, etc. Exit status is 0, unless last command failed or returned nonzero 
status. 

BUGS 

There doesn’t seem to be any way to clear all breakpoints. 

Adb uses the symbolic information in an old and now obsolete format generated by the —go flag of cc(l), it 
should be changed to use the new format used by the dbx debugger and generated by -g. 

Since no shell is invoked to interpret the arguments of the :r command, the customary wild-card and vari- 
able expansions cannot occur. 

Since there is little type-checking on addresses, using a sourcefile address in an inappropriate context may 
lead to unexpected results; ‘main?i will almost certainly not do anything useful. 
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NAME 

addbib - create or extend bibliographic database 
SYNOPSIS 

addbib [-p promptfile] [-a] database 
DESCRIPTION 

When addbib starts up, answering “y” to the initial “Instructions?” prompt yields directions; typing “n” 
or return skips them. Addbib then prompts for various bibliographic fields, reads responses from the ter- 
minal, and sends output records to a database. A null response (just RETURN) means to leave out that field. 
A minus sign (-) means to go back to the previous field. A trailing backslash allows a field to be continued 
on the next line. The repeating “Continue?” prompt allows the user either to resume by typing “y” or 
return, to quit the current session by typing “n” or “q”, or to edit the database with any system editor 
(vi, ex, edit, ed). 

OPTIONS 

-a suppress prompting for an abstract; asking for an abstract is the default. Abstracts are ended with 
a CTRL-d. 

— p use a new prompting skeleton, defined in promptfile. This file should contain prompt strings, a tab, 

and the key-letters to be written to the database. 

BIBLIOGRAPHY KEY LETTERS 

The most common key-letters and their meanings are given below. Addbib insulates you from these key- 
letters, since it gives you prompts in English, but if you edit the bibliography file later on, you will need to 


know this information. 

%A 

Author’s name 

%B 

Book containing article referenced 

%C 

City (place of publication) 

%D 

Date of publication 

%E 

Editor of book containing article referenced 

%F 

Footnote number or label (supplied by refer) 

%G 

Government order number 

%H 

Header commentary, printed before reference 

%I 

Issuer (publisher) 

%J 

Journal containing article 

%K 

Keywords to use in locating reference 

%L 

Label field used by -k option of refer 

%M 

Bell Labs Memorandum (undefined) 

%N 

Number within volume 

%o 

Other commentary, printed at end of reference 

%P 

Page number(s) 

%Q 

Corporate or Foreign Author (unreversed) 

%R 

Report, paper, or thesis (unpublished) 

%S 

Series title 

%T 

Title of article or book 

%V 

Volume number 

%X 

Abstract — used by roffbib, not by refer 

%Y,Z 

ignored by refer 


Except for ‘A’, each field should be given just once. Only relevant fields should be supplied. An example 
is: 


%A Bill Tuthill 

%T Refer — A Bibliography System 

%l Computing Services 
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%C Berkeley 

%D 1982 

%0 UNX 4.3.5. 


FILES 

promptfile optional file to define prompting 
SEE ALSO 

"refer" in Formatting Documents on the Sun Workstation 
refer(l), sortbib(l), roffbib(l), indxbib(l) 


4 


Last change: 26 August 1985 


Sun Release 3.0 



ADJACENTSCREENS ( 1 ) 


USER COMMANDS 


ADJACENTSCREENS ( 1 ) 


NAME 

adjacentscreens — notify the window driver of the physical relationships of screens 
SYNOPSIS 

adjacentscreens [ -c | -m ] center screen [ [ — 1 1 — r | — 1 1 — b ] side screen ] [ -x ] 

DESCRIPTION 

Adjacentscreens tells the mouse cursor tracking mechanism of the window driver how to move between 
screens that contain windows. Once properly notified using adjacentscreens , the mouse cursor slides from 
one screen to another when the user moves the cursor off the edge of a screen. 

OPTIONS 

— c center screen 

The center screen is a frame buffer device name, such as Idevlfb. All the other physical screen 
positions are relative to this reference point. The -c flag (c for center) is optional. If no further 
arguments are present on the command line, center screen is set to have no neighbors. 

— m center screen 

The -m flag ( m for middle) may be used instead of-c. 

-1 side screen 

The side screen is also a frame buffer device name, such as Idev/cgoneO. The -1 flag means that 
side screen is to the / eft of center screen. Up to four repetitions of “flag side screen” may be 
specified on the command line to define the four neighbors of center screen. 

— r side screen 

Like -1, but means that side screen is to the right of center screen. 

— t side screen 

Like -1, but means that side screen is on lop of center screen. 

-b side screen 

Like —I, but means that side screen is b elow center screen. 

-x Suppresses the normal notification to a side screen cursor tracker that center screen is its only 
neighbor. This option is useful if you have a large number of screens or want strange inter- 
window cursor movement. 

EXAMPLE 

A common configuration would be two screens, a monochrome ( Idevlfb ) and a color screen (/ dev/cgoneO ). 
Let us assume that the user has set up an instance of suntools on each screen (the window systems must be 
running before adjacentscreens is run). He would notify the window driver that the color screen was to the 
right of the monochrome screen by running 

“% adjacentscreens /dev/fb -r /dev/cgoneO” in a Shelltool (see suntools(l)). This sets up cursor tracking 
so that the cursor slides from the monochrome screen to the color screen when the cursor moves off the 
right hand side of the monochrome screen. Similarly, the cursor slides from the color screen to the mono- 
chrome screen when the cursor moves off the left hand side of the color screen. 

FILES 

/usr/suntool/adj acentscreens 
SEE ALSO 

suntools(l), login(l) 

BUGS 

Window systems on the screens have to be initialized before running adjacentscreens. 
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NAME 

admin - create and administer SCCS files 

SYNOPSIS 

/usr/sccs/admin [ -n ] [ -i [ name ] ] [ -rrel ] [ -t [ name ] ] [ -f flag [flag-val ] ] . . . 

[ -d flag [flag-val ] ] . . . [ -a login ] . . . [ -do gin ] . . . [ -m [ mrlist ] ] 

[-ylcommentW [-h] [-z] filename ... 

DESCRIPTION 

Admin creates new SCCS files and changes parameters of existing ones. Options and SCCS file names may 
appear in any order on the admin command line. SCCS file names must begin with the characters ‘s.’. A 
named file is created if it doesn’t exist already, and its parameters are initialized according to the specified 
options. Any parameter not initialized by an option is assigned a default value. If a named file does exist, 
parameters corresponding to specified options are changed, and other parameters are left as is. 

If a directory is named, admin behaves as though each file in the directory were specified as a named file, 
except that non-SCCS files (last component of the path name does not begin with s.) and unreadable files 
are silently ignored. A name of - means the standard input — each line of the standard input is taken as 
the name of an SCCS file to be processed. Again, non-SCCS files and unreadable files are silently ignored. 

OPTIONS 

Options are explained as though only one named file is to be processed, since options apply independently 
to each named file. 

-n A new SCCS file is being created. 

-i [name ] 

Initial text: the file name contains the text of a new SCCS file. The text is the first delta of the file 
— see -r option for delta numbering scheme. If name is omitted, the text is obtained from the 
standard input. Omitting the -i option altogether creates an empty SCCS file. You can only create 
one SCCS file with an admin -i command. Creating more than one SCCS file with a single admin 
command requires that they be created empty, in which case the -i option should be omitted. 
Note that the -i option implies the -n option. 

-r rel Initial release: the rel ease into which the initial delta is inserted, -r may be used only if the -i 
option is also used. The initial delta is inserted into release 1 if the -r option is not used. The 
level of the initial delta is always 1, and initial deltas are named 1.1 by default. 

-t [name ] 

Descriptive text: The file name contains descriptive text for the SCCS file. The descriptive text file 
name must be supplied when creating a new SCCS file (either or both -n and -i options) and the 
-t option is used. In the case of existing SCCS files: 1) a -t option without a file name removes 
descriptive text (if any) currently in the SCCS file, and 2) a -t option with a file name replaces the 
descriptive text currently in the SCCS file with any text in the named file. 

-f flag Set flag: specifies a flag, and, possibly, a value for the flag, to be placed in the SCCS file. Several 
-f options may be supplied on a single admin command line. Flags and their values appear in the 
FLAGS section after this list of options. 

-d flag Delete flag from an SCCS file. The -d option may be specified only when processing existing 
SCCS files. Several -d options may be supplied on a single admin command. See the FLAGS 
section below. 

-1 list Unlock the specified list of releases. See the -f option for a description of the 1 flag and the syntax 
of a list. 

-a login Add login name, or numerical UNIX group ID, to the list of users who may make deltas (changes) 
to the SCCS file. A group ID is equivalent to specifying all login names common to that group ID. 
Several -a options may appear on a single admin command line. As many logins, or numerical 
group IDs, as desired may be on the list simultaneously. If the list of users is empty, anyone may 
add deltas. 
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-e login Erase login name, or numerical group ID, from the list of users allowed to make deltas (changes) 
to the SCCS file. Specifying a group ID is equivalent to specifying all login names common to that 
group ID. Several -e options may be used on a single admin command line. 

-y [ comment ] 

The comment text is inserted into the SCCS file as a comment for the initial delta in a manner 
identical to that of delta ( 1). If the -y option is omitted, a default comment line is inserted in the 
form: 

date and time created YY/MM/DD HH:MM:SS by login 

The -y option is valid only if the -i and/or -n options are specified (that is, a new SCCS file is 
being created). 

— m [ mrlist ] 

The list of Modification Requests (MR) numbers is inserted into the SCCS file as the reason for 
creating the initial delta in a manner identical to delta(l). The v flag must be set and the MR 
numbers are validated if the v flag has a value (the name of an MR number validation program). 
Diagnostics are displayed if the v flag is not set or MR validation fails. 

-h Check the structure of the SCCS file (see sccsfile( 5)), and compare a newly computed check-sum 
(the sum of all the characters in the SCCS file except those in the first line) with the check-sum that 
is stored in the first line of the SCCS file. 

The -h option inhibits writing on the file, so that it nullifies the effect of any other options sup- 
plied, and is, therefore, only meaningful when processing existing files. 

-z recompute the SCCS file check-sum and store it in the first line of the SCCS file (see -h, above). 

Using the -z option on a truly corrupted file may prevent future detection of the corruption. 

FLAGS 

The list below is a description of the flags which may appear as arguments to the -f (set flags) and -d 
(delete flags) options. 

b When set, the -b option can be used on a get( 1) command to create branch deltas. 

c ceil The highest release (ceiling) which may be retrieved by a get(l) command for editing. The ceil- 

ing is a number less than or equal to 9999. The default value for an unspecified c flag is 9999. 

f floor The lowest release (floor) which may be retrieved by a get(l) command for editing. The floor is a 
number greater than 0 but less than 9999. The default value for an unspecified f flag is 1. 

d SID The default delta number (SID) to be used by a get( 1) command. 

i Treats the ‘No id keywords (ge6)’ message issued by get( 1) or delta (1) as a fatal error. In the 
absence of the i flag, the message is only a warning. The message is displayed if no SCCS 
identification keywords (see get(\)) are found in the text retrieved or stored in the SCCS file. 

j Concurrent get(\) commands for editing may apply to the same SID of an SCCS file. This allows 
multiple concurrent updates to the same version of the SCCS file. 

Mist A list of locked releases to which deltas can no longer be made. A get-e fails when applied 
against one of these locked releases. The list has the following syntax: 

<list> 

<range> ::= RELEASE NUMBER | a 

The character a in the list is equivalent to specifying all releases for the named SCCS file. 

n The delta (1) command creates a ‘null’ delta in each release (if any) being skipped when a delta is 
made in a new release. For example, releases 3 and 4 are skipped when making delta 5.1 after 
delta 2.7. These null deltas serve as ‘anchor points’ so that branch deltas may be created from 
them later. If the n flag is absent from the SCCS file, skipped releases will be non-existent in the 
SCCS file, preventing branch deltas from being created from them in the future. 
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q text Text is defined by the user. The text is substituted for all occurrences of the %Q% keyword in 
SCCS file text retrieved by get (1). 

m module 

Module name of the SCCS file substituted for all occurrences of the %M% keyword in SCCS file 
text retrieved by get( 1). If the m flag is not specified, the value assigned is the name of the SCCS 
file with the leading s. removed. 

t type Type of module in the SCCS file substituted for all occurrences of %Y% keyword in SCCS file text 
retrieved by get(l). 

v [program] 

Validity checking program', delta(l) prompts for Modification Request (MR) numbers as the rea- 
son for creating a delta. The optional program specifies the name of an MR number validity 
checking program (see delta (\)). If this flag is set when creating an SCCS file, the -m option must 
also be used even if its value is null. 


FILES 

The last component of all SCCS file names must be of the form s .file-name. New SCCS files are given mode 
444 (see chmod(l)). Write permission in the pertinent directory is, of course, required to create a file. All 
writing done by admin is to a temporary x-file, called x.file-name, (see get(Vj), created with mode 444 if 
the admin command is creating a new SCCS file, or with the same mode as the SCCS file if it exists. After 
successful execution of admin, the SCCS file is removed (if it exists), and the x-file is renamed with the 
name of the SCCS file. This ensures that changes are made to the SCCS file only if no errors occurred. 

It is recommended that directories containing SCCS files be mode 755 and that SCCS files themselves be 
mode 444. The mode of the directories allows only the owner to modify SCCS files contained in the direc- 
tories. The mode of the SCCS files prevents any modification at all except by SCCS commands. 

If it should be necessary to patch an SCCS file for any reason, the mode may be changed to 644 by the 
owner allowing use of a text editor. "Care must be taken! " The edited file should always be processed by 
an admin -h to check for corruption followed by an admin -z to generate a proper check-sum. Another 
admin — h is recommended to ensure the SCCS file is valid. 

Admin also uses a transient lock file (called z.file-name), to prevent simultaneous updates to the SCCS file 
by different users. See get( 1) for further information. 

SEE ALSO 

sccs(l), delta(l), ed(l), get(l), help(l), prs(l), what(l), sccsfile(5). 

Source Code Control System in Programming Tools for the Sun Workstation. 

DIAGNOSTICS 

Use help(l) for explanations. 
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NAME 

ar - archive and library maintainer 
SYNOPSIS 

ar d/m/p/q/r/t/x [ abcilouv ] [ posname ] afile name . . . 

DESCRIPTION 

Ar maintains groups of files combined into a single archive/library file. It is normally used to create and 
update library files used by the loader; it can be used, though, for any similar purpose. 

One of the mandatory keys (dmpqrtx) must be used; it may be followed by one or more of the modifiers 
abcilouv. Afile is the archive file. The names are constituent files in the archive file. 

OPTIONS 

d Delete the named files from the archive file, 
m Move the named files to the end of the archive, 
p Display the named files in the archive. 

q Quick append. Append the named files to the end of the archive file without searching the archive 
for duplicate names. Useful only to avoid quadratic behavior when creating a large archive 
piece-by-piece. 

r Replace the named files in the archive file. 

t Display a table of contents of the archive file. If no names are given, all files in the archive are 

listed; if names are given, only those files are listed. 

x Extract the named files. If no names are given, all files in the archive are extracted. In neither 
case does x alter the archive file. 


MODIFIERS 

a Place new files after posname (posname argument must be present). Applies only to the r and m 
options. 

b Place new files before posname (posname argument must be present). Applies only to the r and m 
options. 

c Normally ar creates afile when it needs to, and displays a message to this effect. The c modifier 
suppresses this message. 

i Identical to the b modifier. 

1 Local. Ar places its temporary files in the directory /tmp. The 1 modifier places them in the local 

directory instead. 

o Old date. When files are extracted with the x option, o sets the “last modified” date to the date 
recorded in the archive. 

u Replace only those files that have changed since they were put in the archive. Used with the r 
option. 


v Verbose. Give a file-by-file description of the creation of a new archive file from the old archive 
and the constituent files. When used with t, it gives a long listing of all information about the 
files. When used with p, it precedes each file with a name. 

FILES 

/tmp/v* temporaries 


SEE ALSO 

lorder(l), ld(l), ranlib(l), ar(5) 


BUGS 

If the same file is mentioned twice in an argument list, it is put in the archive twice. 
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The ‘last-modified’ date of a file will not be altered by the o option unless the user is either the owner of the 
extracted file or the superuser. 
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-10 ] [ — m68020 | —20 ] [ — o objfile ] [ — O ] 


— d2 


-e 

-h 


NAME 

as - Sun-2 and Sun-3 assembler 
SYNOPSIS 

as [ -d2 ] [ -e ] [ -h ] [ -j ] [ - J ] [-L] [-m68010 
[ — R ] filename 

DESCRIPTION 

as translates assembly code in the named filename into executable object code in the specified objfile. 

All undefined symbols in the assembly are treated as global. 

The output of the assembly is left in the file objfile. 

OPTIONS 

Specifies that instruction offsets involving forward or external references and having sizes 
unspecified in the assembly language are two bytes long. The default is four bytes. See also the -j 
option. 

Allows control sections to begin on any two-byte boundary, rather than only four-byte boundaries. 

Suppress span-dependent instruction calculations and force all branches to be of medium length, 
but all calls to take the most general form. This is used when assembly time must be minimized, 
but program size and run time are not important. This option results in a smaller and faster pro- 
gram than that produced by the — J option, but some very large programs may not be able to use it 
because of the limits of the medium-length branches. 

Use short (pc-relative) branches to resolve jump’s and jsr’s to externals. This is for compact pro- 
grams which cannot use the — d2 flag because of large program relocation. 

Suppress span-dependent instruction calculations and force all branches and calls to take the most 
general form. This is used when assembly time must be minimized, but program size and run time 
are not important. 

Save defined labels beginning with an ‘L’, which are normally discarded to save space in the 
resultant symbol table. The compilers generate such temporary labels. 

-m68010 

-10 Accept only MC68010 instructions and addressing modes, and put the MC68010 machine-type 
tag in the object file. 

-m68020 

-20 Accept the full MC68020 and MC6888 1 instruction sets and addressing modes, and put the 
MC68020 machine-type tag in the object file. 

The next argument is taken as the name of the object file to be produced. If the -o flag isn’t used, 
the objfile is named a. out. 

Perform span-dependent instruction resolution over entire files rather than just over individual 
procedures. 

Make initialized data segments read-only by concatenating them to the text segments. This elim- 
inates the need to run editor scripts on assembly code to make inidalized data read-only and 
shared. 


-J 


-J 


-L 


-o 


-O 


-R 


FILES 


/tmp/as* 


default temporary file 


SEE ALSO 

ld(l), nm(l), adb(l), dbx(l), a.out(5) 

The “Assembler Reference Manual for the Sun Workstation’ ' in the Sun Programming Tools Manual 
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BUGS 

The Pascal compiler, pc, qualifies a nested procedure name by chaining the names of the enclosing pro- 
cedures. This sometimes results in names long enough to abort the assembler, which currently limits 
identifiers to 512 characters. 
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NAME 

at - execute commands at a later time 
SYNOPSIS 

at time [ day ] [ file ] 

DESCRIPTION 

At squirrels away a copy of the named file (standard input default) to be used as input to sh(l) or csh( 1) at 
a specified later time. At inserts a cd command to the current directory at the beginning of the copy file, 
and follows this with assignments to all environment variables (except TERM, which is useless in this con- 
text.) When the script is run, it uses the user and group ID of the creator of the copy file. 

Time is specified by from 1 to 4 digits, and may be followed by ‘a’, ‘p’, ‘n’ or ‘m’ for AM, PM, noon, or 
midnight (letters may be upper or lower case). One and two digit numbers are taken to be hours, three and 
four digits to be hours and minutes. If no letters follow the digits, a 24 hour clock time is understood. 

Day may be either a month name followed by a day number — for example, ‘apr 26’ — or a day of the 
week — ‘weds’, for instance. If you name a day of the week and follow this with the word ‘week’ — 
‘weds week’ — invocation is moved seven days further off. Names of months and days may be recogniz- 
ably truncated. 

At programs are executed by periodic execution of the command lusrlliblatrun from cron{ 8). The granu- 
larity of at depends upon how often atrun is executed. 

Standard output or error output is lost unless redirected. 

EXAMPLES 

Examples of legitimate commands are: 
at8ajan24 
at 1530 fr week 

FILES 

/usr/lib/atrun 

in /usr/spool/at: 

yy.ddd.hhhh.* 
lasttimedone 
past 

SEE ALSO 

calendar(l), pwd(l), sleep(l), cron(8) 

BUGS 

Due to the granularity of the execution of lusrlliblatrun, there may be bugs in scheduling things almost 
exactly 24 hours into the future. 


executor (run by cron(8)). 

activity for year yy, day dd, hour hhhh. 
last hhhh 

activities in progress 
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NAME 

awk - pattern scanning and processing language 
SYNOPSIS 

awk [ -f program Jile ] [ -Fc ] [ program ] [file . . . ] 

DESCRIPTION 

Awk scans each of its input files for lines that match any of a set of patterns specified in program. The 
input files are read in order; the standard input is read if there are no files. The filename means the 
standard input. 

The set of patterns may either appear literally on the command line as program, or, by using the -f option, 
the set of patterns may be in a program Jile. 

With each pattern in program there can be an associated action that will be performed when a line of a file 
matches the pattern. See the discussion below for the format of input lines and the awk language. Each 
line in each input file is matched against the pattern portion of every pattern-action statement; the associ- 
ated action is performed for each matched pattern. 

OPTIONS 

— f program Jile 

Use the contents of program Jle as the source for the program. 

— F c Use the character c as the field separator (FS) character. See the discussion of FS below. 

LINES, STATEMENTS, AND THE AWK LANGUAGE 
Input Lines 

An input line is made up of fields separated by white space. The field separator can be changed by using 
FS — see below. Fields are denoted $1, $2, ... up to $9; $0 refers to the entire line. 

Pattern-action Statements 
A pattern-action statement has the form 

pattern { action } 

A missing { action } means copy the line to the output; a missing pattern always matches. 

An action is a sequence of statements. A statement can be one of the following: 

if ( conditional ) statement [ else statement ] 

while ( conditional ) statement 

for ( expression ; conditional ; expression ) statement 

break 

continue 

{ [ statement] ... } 

variable = expression 

print [ expression-list ] [ expression ] 

printf format [ , expression-list ] [ expression ] 

next # skip remaining patterns on this input line 

exit # skip the rest of the input 

Format of the Awk Language 

Statements are terminated by semicolons, newlines or right braces. An empty expression-list stands for the 
whole line. 

Expressions take on string or numeric values as appropriate, and are built using the operators +, %, 

and concatenation (indicated by a blank). The C operators ++, — , +=, — =, *=, /=, and %= are also avail- 
able in expressions. 

Variables may be scalars, array elements (denoted x [ i ]) or fields. Variables are initialized to the null 
string. Array subscripts may be any string, not necessarily numeric, providing a form of associative 
memory. String constants are quoted ". . .". 
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The print statement prints its arguments on the standard output (or on a file if >file is present), separated by 
the current output field separator, and terminated by the output record separator. The printf statement for- 
mats its expression list according to the format template (see printf(5S) for a description of the formatting 
control characters). 

Built In Functions 

The built-in function length returns the length of its argument taken as a string, or of the whole line if no 
argument There are also built-in functions exp, log, sqrt, and int, where int truncates its argument to an 
integer. substr(s,m,n) returns the n -character substring of s that begins at position m. The 
sprintf (format, expr, expr, ...) function formats the expressions according to the printf OS) format given by 
format and returns the resulting string. 

Patterns 

Patterns are arbitrary Boolean combinations (!, ||, &&, and parentheses) of regular expressions and rela- 
tional expressions. Regular expressions must be surrounded by slashes and are as in egrep. Isolated regu- 
lar expressions in a pattern apply to the entire line. Regular expressions may also occur in relational 
expressions. 

A pattern may consist of two patterns separated by a comma; in this case, the action is performed for all 
lines between an occurrence of the first pattern and the next occurrence of the second. 

A relational expression is one of the following: 

expression matchop regular-expression 
expression relop expression 

where a relop is any of the six relational operators in C, and a matchop is either " (for contains) or !" (for 
does not contain). A conditional is an arithmetic expression, a relational expression, or a Boolean combi- 
nation of these. 

The special pattern BEGIN may be used to capture control before the first input line is read, in which case 
BEGIN must be the first pattern. The special pattern END may be used to capture control after the last 
input line is read, in which case END must be the last pattern. 

Special Variable Names 

A single character c may be used to separate the fields by starting the program with 
BEGIN { FS = "c” } 
or by using the -Fc option. 

Other variable names with special meanings include NF, the number of fields in the current record; NR, the 
ordinal number of the current record; FILENAME, the name of the current input file; OFS, the output field 
separator (default blank); ORS, the output record separator (default newline); and OFMT, the output for- 
mat for numbers (default "%.6g"). 

EXAMPLES 

Print lines longer than 72 characters: 
length > 72 

Print first two fields in opposite order: 

{ print $2, $1 } 

Add up first column, print sum and average: 

{s+=$l} 

END { print "sum is", s, " average is", s/NR } 

Print fields in reverse order: 

{ for (i = NF; i > 0; — i) print $i } 
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Print all lines between start/stop pairs: 

/start/, /stop/ 

Print all lines whose first field is different from previous one: 

$1 != prev { print; prev = $1 } 

SEE ALSO 

Using UNIX Text Utilities on the Sun Workstation 
sed(l), grep(l), lex(l) 

BUGS 

There are no explicit conversions between numbers and strings. To force an expression to be treated as a 
number add 0 to it; to force it to be treated as a string concatenate "" to it 

Syntax errors result in the cryptic message "awk bailing out near line 1!!." 
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NAME 

basename - strip filename affixes 
SYNOPSIS 

basename string [ suffix ] 

DESCRIPTION 

basename deletes any prefix ending in 7 ’ and the suffix, if present in string, from string, and directs the 
result to the standard output. It is normally used inside substitution marks ' ' in shell procedures. 
EXAMPLE 

This shell procedure invoked with the argument lusrlsrclbinlcat.c compiles the named file and moves the 
output to cat in the current directory: 

cc $1 

mv a.out 'basename $1 .c' 

SEE ALSO 

sh(l) 
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NAME 

be - arbitrary-precision arithmetic language 
SYNOPSIS 

be [ — c ] [ — 1 ] [ file — ] 

DESCRIPTION 

Be is an interactive processor for a language which resembles C but provides unlimited precision arith- 
metic. Be takes input from any files given, then reads the standard input. The syntax for be programs is as 
follows; L means letter a-z, E means expression, S means statement. 

Comments 

are enclosed in /* and */. 


Names 

simple variables: L 
array elements: L [ E ] 

The words ‘ibase’, ‘obase’, and ‘scale’ 

Other operands 

arbitrarily long numbers with optional sign and decimal point 
(E) 

sqrt ( E ) 

length ( E ) number of significant decimal digits 
scale ( E ) number of digits right of decimal point 
L(E E) 

Operators 

+ - * / % A (% is remainder; A is power) 

++ — (prefix and postfix; apply to names) 

== <= >=!=<> 

= += -= *= /= %= A = 

Statements 

E 

{ S ; ; S } 
if ( E ) S 
while ( E ) S 
for ( E ; E ; E ) S 
null statement 
break 
quit 

Function definitions 

define L ( L ,. . ., L ) { 
auto L, . . . , L 
S; ... S 
return ( E ) 

} 


Functions in - 

-1 math library 

s(x) 

sine 

c(x) 

cosine 

e(x) 

exponential 

l(x) 

log 

a(x) 

arctangent 

j(n,x) 

Bessel function 
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All function arguments are passed by value. 

The value of a statement that is an expression is printed unless the main operator is an assignment Either 
semicolons or newlines may separate statements. Assignment to scale influences the number of digits to be 
retained on arithmetic operations in the manner of dc( 1). Assignments to ibase or obase set the input and 
output number radix respectively. 

The same letter may be used as an array, a function, and a simple variable simultaneously. All variables 
are global to the program. ‘Auto’ variables are pushed down during function calls. When using arrays as 
function arguments or defining them as automatic variables empty square brackets must follow the array 
name. 

EXAMPLES 

Define a function to compute an approximate value of the exponential function: 
scale = 20 
define e(x){ 

auto a, b, c, i, s 
a = 1 
b = 1 
s = 1 

for(i=l; 1==1; i++){ 
a = a*x 
b = b*i 
c = a/b 

if(c == 0) retum(s) 
s = s+c 

} 

} 


Print approximate values of the exponential function of the first ten integers: 
for(i=l; i<=10; i++) e(i) 

OPTIONS 

-1 is the name of an arbitrary precision math library. 

-c Compile only: be is actually a preprocessor for dc( 1), which it invokes automatically, unless the 
-c (compile only) option is present In this case the dc input is sent to the standard output instead. 

FILES 

/usr/lib/lib.b mathematical library 
dc( 1) desk calculator proper 

SEE ALSO 

dc(l) 

L. L. Cherry and R. Morris, BC - An arbitrary precision desk-calculator language 

BUGS 

For statement must have all three E’s. 

Quit is interpreted when read, not when executed. 


Sun Release 3.0 


Last change: 1 April 1981 


19 



BIFF(l) 


USER COMMANDS 


BIFF ( 1 ) 


NAME 

biff - mail alarm 

SYNOPSIS 

biff [ y|n ] 

DESCRIPTION 

biff informs the system whether you want to be notified when mail arrives during the current terminal ses- 
sion. The command: 
biffy 

enables notification; the command: 
biff n 

disables it; finally, the command: 
biff 

on its own tells you whether the notification is y or n. When mail notification is enabled, the header and 
first few lines of the message are printed on your screen whenever mail arrives. A biff y command is often 
included in the file .login or .profile to be executed at each login. 

biff operates asynchronously. For synchronous notification use the MAIL variable of sh or the mail variable 
of csh. 

SEE ALSO 

csh(l), sh(l), mail(l), comsat(8) 
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NAME 

/bin/mail - send or receive mail among users 
SYNOPSIS 

/bin/mail [ — i ] [ — p ] [ — q ] [ — f filename ] 

/bin/mail address . . . 

DESCRIPTION 

Note: This is the old version 7 UNIX system mail program. The default mail command is described in 
mail(l), and its binary is in the directory lusr/ucb. 

/bin/mail with no address prints a user’s mail, message-by-message in last-in, first-out order. Ibin/mcdl 
accepts commands from the standard input to direct disposition messages. 

When addresses are named, /bin/ mail takes the standard input up to an end-of-file (or a line with just V) 
and adds it to each person's ‘mail’ file. The message is preceded by the sender’s name and a postmark. 
Lines that look like postmarks are prepended with “>’. A person is usually a user name recognized by 
login, or a network address (see mailaddr(7)). 

If there is any pending mail, login tells you there is mail when you log in. It is also possible to have the C- 
Shell, or the daemon biff tell you about mail that arrives while you are logged in. 

OPTIONS 

Printing Mail 

-i continue after interrupts — an interrupt normally terminates the lbinlma.il accepts the following 
interactive commands when printing messages. 

-p print messages without prompting for commands. Exit immediately upon receiving an interrupt, 
-q quit immediately upon interrupt. 

-f filename 

use filename as if it were the mail file. 

Sending Mail 

— d deliver mail directly, don’t route the message through sendmail. This option is often used by pro- 

grams that send mail. 

-i continue after interrupts — an interrupt normally terminates the /bin/mail command and leaves the 
mail file unchanged. 

— r name 

specify a string to appear as the name of the sender. 

COMMANDS 

? print a command summary. 

EOT (control-D) 

put unexamined mail back in the mail file and quit. 

! command 

escape to the Shell to do command. 

- go back to previous message. 

+ go on to next message, 
newline go on to next message, 
d delete message and go on to the next, 
dq delete message and quit, 
m [ person ] ... 

mail the message to the named persons (yourself is default). 
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n go on to next message, 

p print message (again), 

q same as EOT. 

s [file ] ... 

save the message in the named files (‘mbox’ default). If saved successfully, remove it from the 
list and go on to the next message. 

w [file ] ... 

save the message, without a header, in the named files (‘mbox’ default). If saved successfully, 
remove it from the list and go on to the next message. 

x exit without changing the mail file. 

FILES 

/etc/passwd to identify sender and locate address 
/usr/spool/mail/* incoming mail for user * 

mbox saved mail 

/tmp/ma* temp file 

/usr/spool/mail/ * .lock lock for mail directory 
dead.letter unmailable text is saved here 

SEE ALSO 

mail(l), biff(l), write(l), uucp(lC), uux(lC), xsend(l), sendmail(8), mailaddr(7), csh(l) 

BUGS 

Race conditions sometimes result in a failure to remove a lock file. 

The superuser can read your mail, unless it is encrypted by des, encrypt, or xsend. Even if you encrypt it, 
the superuser can delete it. 
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NAME 

cal - display calendar 

SYNOPSIS 

cal [ month ] year 

DESCRIPTION 

Cal displays a calendar for the specified year. If a month is also specified, a calendar for that month only is 
displayed. 

Year can be between 1 and 9999. Be aware that ‘cal 78’ refers to the early Christian era, not the 20th cen- 
tury. Also, the year is always considered to start in January, even though this is historically naive. 

Month is a number between 1 and 12. 

The calendar produced is that for England and her colonies. 

Try September 1752. 
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NAME 

calendar - reminder service 

SYNOPSIS 

calendar [ - ] 

DESCRIPTION 

Calendar consults the file calendar in the current directory and displays lines that contain today’s or 
tomorrow’s date anywhere in the line. Most reasonable month-day dates — such as ‘Dec. 7,’ ‘december 
7,’ and ‘12/7’ — are recognized; but ‘7 December’ or ‘7/12’ are not. If you give the month as with a 
date — for example, “* 1” — that day in any month will do. On weekends ‘tomorrow’ extends through 
Monday. 

When the optional - argument is present, calendar does its job for every user who has a file calendar in his 
login directory and sends him any positive results by mail{\)- Normally this is done daily in the wee hours 
under control of cron (8). 

The file calendar is first run through the C preprocessor, llib/cpp, to include any other calendar files 
specified with the usual “finclude” syntax. Included calendars are usually shared by all users, and main- 
tained by the system administrator. 

FILES 

'/calendar 

/usr/lib/calendar to figure out today’s and tomorrow’s dates 

/etc/passwd 

/tmp/cal* 

/lib/cpp subprocess 
/usr/bin/egrep subprocess 

/bin/sed subprocess 
/bin/mail subprocess 

SEE ALSO 

at(l), cron(8), mail(l) 

BUGS 

Calendar’s extended idea of ‘tomorrow’ doesn’t account for holidays. 
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NAME 

cat - concatenate and display 
SYNOPSIS 

cat [ -u ] [ -n ] [ -b ] [ -s ] [ -v ] [-e] [ -t ] [-] [file...] 

DESCRIPTION 

Cat reads each file in sequence and displays it on the standard output. Thus 
% cat goodies 

displays the contents of goodies on the standard output, and 
% cat filel flle2 >file3 

concatenates the first two files and places the result on the third. 

If no filename argument is given, or if the argument is given, cat reads from the standard input file. If 
the standard input is a terminal, input is terminated by a A D. 

OPTIONS 

-u makes the output completely unbuffered. If -u is not used, output is buffered in 1024-byte blocks, 

or line-buffered if standard output is a terminal. 

-n precedes each line output with its line number. 

— b numbers the lines, as — n, but omits the line numbers from blank lines. 

— s substitutes a single blank line for multiple adjacent blank lines. 

-v displays non-printing characters so that they are visible. Control characters print like "X for 
control-x; the delete character (octal 0177) prints as *?. Non-ASCH characters (with the high bit 
set) are displayed as M- (for meta) followed by the character of the low 7 bits. 

-e displays non-printing characters, as -v, and in addition displays a *$’ character at the end of each 
line. 

-t displays non-printing characters, as -v, and in addition displays tab characters as ‘T. 

SEE ALSO 

cp(l), ex(l), more(l), pr(l), tail(l) 

BUGS 

Beware of ‘cat a b >a’ and ‘cat a b >b’, which destroy the input files before reading them. 
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NAME 

cb - C program beautifier 
SYNOPSIS 

cb 

DESCRIPTION 

cb places a copy of the C program from the standard input on the standard output with spacing and indenta- 
tion that displays the structure of the program. 

SEE ALSO 

indent(l) 

BUGS 

indent(\) is preferred. 
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NAME 

cc - C compiler 
SYNOPSIS 

cc [ c ] [-g] [-o output] [ -O ] [-a] [ -Aasmflags ] [ -C ] [ -D name ] [-D name=def] [-E] 

[ -fsingle ] [ float _option ] [ -go ] [ -I dir ] [ -p ] [ -pg ] [ -R ] [ -S ] 

[ ~t [ p|0|2|a|c|l ] ] [ -B string ] [ -U name ] [ -v ] [ -w ] filename . . . 

DESCRIPTION 

Cc is the UNIX C compiler which translates programs written in the C programming language into execut- 
able load modules, or into relocatable binary programs for subsequent loading with the ld( 1) linker. 

In addition to the many options, cc accepts several types of files. Files whose names end with .c are taken 
to be C source programs; they are compiled, and each resulting object program is left in the current direc- 
tory, with the same name as the source file, except that the .c suffix is replaced by .o. In the same way, files 
whose names end with ^ are taken to be assembly source programs and are assembled, producing a .o file. 

Other arguments are taken to be loader option arguments, object programs, or libraries of object programs. 
Unless -c, -S, or -E is specified, these programs and libraries, together with the results of any compila- 
tions or assemblies specified, are loaded (in the order given) to produce an executable program named 
a. out. The name a. out can be overridden with the loader’s -o option. 

If a single C program is compiled and loaded all at once, the intermediate .0 file is deleted. 

OPTIONS 

The following options are interpreted by cc. See ld{ 1) for load-time options. 

-c Compile only — suppress the loading phase, and force an object file to be produced even if only 
one program is compiled. 

-g Produce additional symbol table information for dbx(l) and pass the -Ig flag to ld( 1). 

-o output 

Name the final output file output. If this option is used, the file a. out is left undisturbed. 

-O Invoke the object code optimizer to improve the generated code. This option should be used for 
all production code, though not during development, since it slows the compiler down. 

-a Insert code into the program to count how many times each basic block in the program is exe- 
cuted. This process is performed after the C preprocessor cpp has run but before compilation 
takes place. After the program is compiled with this option, there will be a .d file for every .c file. 
The A file accumulates execution data for the corresponding source file. The fcov(l) utility can 
then be run on the source file to generate statistics about the program. The -a option must be 
used when linking with the cc(l) or W(l) command also. 

—Aasmflags 

Pass asmflags to the assembler as in its command line. For example, -A-j would pass the -j 
option to tell the assembler to use short PC-relative instructions for subroutine calls. 

-C Prevent the C preprocessor from removing comments. 

— D name 
—Dname=def 

Define name to the preprocessor, as if by ‘tdefine’. If no definition is given, the name is defined 
as "1". 

-E Run only the C preprocessor on the named C programs, and send the result to the standard out- 
put. 

-fsingle Use single-precision arithmetic in computations involving only float numbers — that is, do not 
convert everything to double, which is the default. Note that floating-point parameters are still 
converted to double precision, and functions which return values still return double precision 
values. Certain programs ran much faster using this option, but be aware that some significance 
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can be lost due to lower precision intermediate values. 
float_option 

Floating point code generation option. Can be one of: 

— fsoft software floating-point calls (this is the default). 

—fsky in-line code for Sky floating-point processor (supported only on Sun-2). 

-f68881 in-line code for Motorola MC6888 1 floating-point processor (supported only on 
Sun-3). 

-fswitch run-time-switched floating-point calls. The compiled object code is linked at run- 
time to routines that support one of the above types of floating point code. This was 
the default in previous releases. Only for use with programs that are floating-point 
intensive, and must be portable to machines with various floating-point options. 

When invoked without float option, the compiler interrogates the FLOAT_OPTION environ- 
ment variable to determine the type of floating-point code to generate. Legal values for 
FLOAT OPTION are: ‘fsoft’, ‘fsky’, ‘f68881’, ‘ffpa’ and ‘fswitch’. 

-go Produce additional symbol table information in an older format used by the adb debugger and 
pass the -lg flag to ld( 1). 

-I dir ‘#include’ files whose names do not begin with 7’ are always sought first in the directory of the 

file argument, then in directories named in -I options, then in the lusr/include directory. 

-p Produce profiling code to count the number of times each routine is called. If loading takes 
place, replace the standard startup routine by one that automatically calls monitor (3) and use a 
special profiling library in lieu of the standard C library. When the program is run, the file 
mon. out is created. An execution profile can then be generated by use of prof. 

-pg Produce profiling code in the manner of -p, but invoke a run-time recording mechanism that 
keeps more extensive statistics and produces a gmon.out file at normal termination, gprof(l) 
generates an execution profile. 

-R Passed on to as(l), making initialized variables shared and read-only. 

-S Compile the named C programs and leave the assembly language output on corresponding files 

suffixed .j. 

-t[p012acl] 

Use the designated compiler components in the directory named in the -B option. In the absence 
of a -B option, the directory is taken to be lusrlnew. The combinations that can be specified for 
the -t option are: 

p cpp — the C preprocessor. 

0 ccom — the C compiler proper. 

2 c2 — the assembly code optimizer, 
a as — the assembler, 

c libc — the C library. 

1 Id — the loader. 

-B string Find substitute compiler components in the directory string, which must be a pathname ter- 
minated with a slash (/). 

-Vname Remove any initial definition of name for the C preprocessor. 

-v Display a message on standard error indicating the argument string that invoked each phase of 
the compiler. 

-w Suppress warning messages. 
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FILES 


file.c 

C source file 

file.s 

assembler source file 

file.o 

object file 

file.a 

library of object files 

a.out 

executable output file 

/tmp/ctm? 

compiler temporary file 

/lib/Fcrtl.o 

startup code for -fsoft option 

/lib/Mcrtl.o 

startup code for -f68881 option 

/lib/Scrtl.o 

startup code for — fsky option 

/lib/cpp 

macro preprocessor 

/usr/lib/bb count 

block counting preprocessor 

/lib/ccom 

compiler 

/lib/c2 

optional optimizer 

/lib/crtO.o 

runtime startoff 

/lib/mcrtO.o 

startoff for profiling 

/usr/lib/gcrtO.o 

startoff for gprof-profiling 

/usr/lib/bb_link.o 

basic block counting routine 

/lib/fcrtO.o 

SKY runtime startoff 

/lib/fmcrtO.o 

SKY startoff for profiling 

/usr/lib/fgcrtO.o 

SKY startoff for gprof-profiling 

/lib/libc.a 

standard library, see intro (3) 

/usr/lib/libc_p.a 

profiling library, see intro (3) 

/usr/include 

standard directory for ‘#include’ files 

mon.out 

file produced for analysis by prof{ 1) 

gmon.out 

file produced for analysis by gprof(l) 

/usr/new 

default directory for components listed in the -t option 


SEE ALSO 

B. W. Kemighan and D. M. Ritchie, The C Programming Language, Prentice-Hall, 1978 

UNIX Programming in Programming Tools for the Sun Workstation 

monitor(3), prof(l), gprof(l), tcov(l), adb(l), ar(l), ld(l), dbx(l), as(l), diff(l), cpp(l) 

DIAGNOSTICS 

The diagnostics produced by C itself are intended to be self-explanatory. Occasional obscure messages 
may be produced by the preprocessor, assembler, or loader. 

BUGS 

Options that are identical to cc options cannot be passed to the assembler, optimizer or loader. 

The program context given in syntax error messages is taken from the input text after the C preprocessor 
has performed substitutions. Therefore, error messages involving syntax errors in or near macro references 
or manifest constants may be misleading. 
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NAME 

cd - change working directory 

SYNOPSIS 

cd [ directory ] 

DESCRIPTION 

Directory becomes the new working directory. The process must have execute (search) permission in 
directory. If cd is used without arguments, it returns you to your login directory. In cj7i(1) you may 
specify a list of directories in which directory is to be sought as a subdirectory if it is not a subdirectory of 
the current directory; see the description of the cdpath variable in csfc(l). 

SEE ALSO 

csh(l), sh(l), pwd(l) 
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NAME 

cdc - change the delta commentary of an SCCS delta 
SYNOPSIS 

/usr/ucb/sccs/cdc -r SID [ -m [ mrlist ] ] [ -y [ comment ] ] filename . . . 

DESCRIPTION 

cdc changes the delta commentary, for the SID specified by the -r option, of each named SCCS filename. 

Delta commentary is defined to be the Modification Request (MR) and comment information normally 
specified via the delta command (-m and -y options). 

If a directory is named, cdc behaves as though each file in the directory were specified as a named 
filename, except that non-SCCS files (last component of the path name does not begin with s.) and unread- 
able files are silently ignored. If a name of - is given, the standard input is read (see WARNINGS); each line 
of the standard input is taken to be the name of an SCCS file to be processed. 

Arguments to cdc, which may appear in any order, consist of options and file names. 

OPTIONS 

All the described options apply independently to each named file: 

-tSID Specifies the SCCS /Identification (S/D) string of a delta for which the delta commentary is to 
be changed. 

-m[ mrlist) If the SCCS file has the v flag set (see admin(\)), a list of MR numbers to be added and/or 
deleted in the delta commentary of the SID specified by the -r option may be supplied. A null 
MR list has no effect. 

MR entries are added to the list of MRs in the same manner as that of delta. In order to delete 
an MR, precede the MR number with the character ! (see EXAMPLES). If the MR to be 
deleted is currendy in the list of MRs, it is removed and changed into a “comment” line. A 
list of all deleted MRs is placed in the comment section of the delta commentary and preceded 
by a comment line stating that they were deleted. 

If -m is not used and the standard input is a terminal, the prompt MRs? is issued on the stan- 
dard output before the standard input is read; if the standard input is not a terminal, no prompt 
is issued. The MRs? prompt always precedes the comments? prompt (see -y option). 

MRs in a list are separated by blanks and/or tab characters. An unescaped new-line character 
terminates the MR list. 

Note that if the v flag has a value (see admin (l)), it is taken to be the name of a program (or 
shell procedure) which validates the correctness of the MR numbers. If a non-zero exit status 
is returned from the MR number validation program, cdc terminates and the delta commen- 
tary remains unchanged. 

-y [comment] 

Arbitrary text used to replace the comment (s) already existing for the delta specified by the -r 
option. The previous comments are kept and preceded by a comment line stating that they 
were changed. A null comment has no effect. 

If -y is not specified and the standard input is a terminal, the prompt comments? is issued on 
the standard output before the standard input is read; if the standard input is not a terminal, no 
prompt is issued. An unescaped new-line character terminates the comment text 

The exact permissions necessary to modify the SCCS file are documented in Source Code Control System. 
Simply stated, they are either (1) if you made the delta, you can change its delta commentary; or (2) if you 
own the file and directory you can modify the delta commentary. 

EXAMPLES 
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tutorial cdc -rl.6 -m"bl78-12345 !bl77-54321 bI79-00001" -ytrouble s.file 
adds bl78- 12345 and bl79-00001 to the MR list, removes bl77-54321 from the MR list, and adds the com- 
ment trouble to delta 1.6 of s.file. 

tutorial% cdc -rl.6 s.file 
MRs? !bl77-54321 bl78-12345 bl79-00001 
comments? trouble 
does the same thing. 

WARNINGS 

If SCCS file names are supplied to the cdc command via the standard input (- on the command line), then 
the -m and -y options must also be used. 

FILES 

x-file (see delta( 1)) 

z-file (see delta(l)) 

SEE ALSO 

admin(l), comb(l), delta(l), get(l), help(l), prs(l), sccs(l), sccsdiff(l), sccsfile(5), val(l), what(l) 

Source Code Control System in Programming Tools for the Sun Workstation. 

DIAGNOSTICS 

Use help for explanations. 
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NAME 

checknr - check nroff/troff files 
SYNOPSIS 

checknr [ -s ] [ -f ] [ -a jd.yljc2.y2 . . . jcn.yn ] [ -c jc1jc2jc3 ...jc n] [filename ... ] 

DESCRIPTION 

Checknr checks a list of nroff(l) or tr off ( 1 ) input files for certain kinds of errors involving mismatched 
opening and closing delimiters and unknown commands. If no files are specified, checknr checks the stan- 
dard input. Delimiters checked are: 

(1) Font changes using \fic . . . \fP. 

(2) Size changes using \sx . . . \s0. 

(3) Macros that come in open . . . close forms, for example, the .TS and .TE macros which must 
always come in pairs. 

Checknr knows about the ms(J) and me (7) macro packages. 

Checknr is intended to be used on documents that are prepared with checknr in mind. It expects a certain 
document writing style for \f and \s commands, in that each \fx must be terminated with \fP and each \sx 
must be terminated with \s0. While it will work to directly go into the next font or explicitly specify the 
original font or point size, and many existing documents actually do this, such a practice will produce com- 
plaints from checknr. Since it is probably better to use the \fP and \s0 forms anyway, you should think of 
this as a contribution to your document preparation style. 

OPTIONS 

-s Ignore \s size changes. 

-f Ignore \f font changes. 

-a Add pairs of macros to the list The pairs of macros are assumed to be those (such as .DS and 
X)E) that should be checked for balance. The —a option must be followed by groups of six char- 
acters, each group defining a pair of macros. The six characters are a period, the first macro name, 
another period, and the second macro name. For example, to define a pair .BS and .ES, use 
-a.BSJES 

-c define commands which checknr would otherwise complain about as undefined. 

SEE ALSO 

nroff(l), troff(l), ms(7), me(7), checkeq(l) 

BUGS 

There is no way to define a 1 character macro name using -a 
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NAME 

chgrp - change group 
SYNOPSIS 

chgrp [ -f ] group file ... 

DESCRIPTION 

Chgrp changes the group-ID of the files to group. The group may be either a decimal GID or a group 
name found in the group-ID file. 

The user invoking chgrp must belong to the specified group and be the owner of the file, or be the super- 
user. 

No errors are reported when the — f (force) option is given. 

FILES 

/etc/group 

SEE ALSO 

passwd(5), group(5) 
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NAME 

chmod - change mode 

SYNOPSIS 

chmod mode file . . . 

DESCRIPTION 

The mode of each named file is changed according to mode, which may be absolute or symbolic. An abso- 
lute mode is an octal number constructed from the OR of the following modes: 

4000 set user ID on execution 
2000 set group ID on execution 

1000 sticky bit, see chmod(2) 

0400 read by owner 

0200 write by owner 

0100 execute (search in directory) by owner 

0070 read, write, execute (search) by group 

0007 read, write, execute (search) by others 

A symbolic mode has the form: 

[ who ] op permission [ op permission ]. . . 

The who part is a combination of the letters u (for user’s permissions), g (group) and o (other). The letter a 
stands for all, or ugo. If who is omitted, the default is a but the setting of the file creation mask (see umask 
in sh{ 1) or csh (l]for moreinformation ) is 

Op can be + to add permission to the file’s mode, - to take away permission and = to assign permission 
absolutely (all other bits for that category, owner, group, or others, will be reset). 

Permission is any combination of the letters r (read), w (write), x (execute), s (set owner or group id) and t 
(save text - sticky). Letters u, g or o indicate that permission is to be taken from the current mode. Omit- 
ting permission is only useful with = to take away all permissions. 

EXAMPLES 

The first example denies write permission to others, the second makes a file executable: 

chmod o-w file 
chmod +x file 

Multiple symbolic modes separated by commas may be given. Operations are performed in the order 
specified. The letter s is only useful with u or g. 

Only the owner of a file (or the super-user) may change its mode. 

SEE ALSO 

ls(l), chmod(2), chown(8) 
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NAME 

chsh - change default login shell 
SYNOPSIS 

chsh username [ shell ] 

DESCRIPTION 

Chsh changes the login shell field of the user’s password file entry. If no shell is specified, the shell reverts 
to the default login shell Ibinlsh. To specify a shell other than Ibinlcsh, you must be the super-user. 

EXAMPLES 

angel% chsh bill /bin/csh 

SEE ALSO 

csh(l), passwd(l), passwd(5) 
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NAME 

clear — clear screen 

SYNOPSIS 

clear 

DESCRIPTION 

Clear clears your screen if this is possible. It looks in the environment for the terminal type and then in 
letcltermcap to figure out how to clear the screen. 

FILES 

/etc/termcap terminal capability data base 
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NAME 

clearcolormap - clear the color map 

SYNOPSIS 

clear_colormap 

DESCRIPTION 

Clear colormap clears your hardware colormap. 
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NAME 

click - control the keyboard keystroke click sound 
SYNOPSIS 

click [ -y ] [ -n ] [ -d keyboard device ] 

DESCRIPTION 

Change the setting of the audible keyboard click. The default is no keyboard click. If you want to turn 
clicking on then a good place to do it is in /etc/rc.local. 

Only keyboards that support a clicker respond to this command. At the time of this writing, the only key- 
board known to have a clicker is the Sun 3 keyboard. 

OPTIONS 

-y Yes, enable clicking. 

-n No, disable clicking. 

— d keyboard device 

Specify the keyboard device being set. The default is Idevlkbd. 

SEE ALSO 

kb(4s) 

DIAGNOSTICS 

A short help message is printed if an unknown flag is specified or if the -d switch is used and the keyboard 
device name is not supplied. A diagnostic is printed if the keyboard device name can’t be opened or is not 
a keyboard type device. 

BUGS 

There is no way to determine the state of the keyboard click setting. 
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NAME 

clock - display the time in a window 
SYNOPSIS 

clock [-s] [ — t ] [-r] [-dmdyaw] [-f] 

DESCRIPTION 

clock is a standard tool provided with the SunView environment. 

clock displays the current time in its own window. In its open state, clock shows the date and time textual 

form. In its closed state, clock appears as a clock face which keeps time. 

Note: In previous releases clock was known as clocktool. In the current release, clocktool is retained as a 
symbolic link to clock. 

OPTIONS 

-r causes clock to use a square face with roman numerals in the iconic state. This replaces the 
default round clock face. 

-d display date information in a small area just below the clock face. The date information to be 
displayed may include: 

m the month, 

d the day of the month (1-31), 

y the year, 

a the string AM or PM, as appropriate, 

w the day of the week (Sun-Sat). 

There is only room for 3 of these, but any 3 may be displayed in any sequence. 

-f Display the date and day of week on the clock face. 

-s start clock with the seconds turned on. By default, the clock starts with seconds turned off, and 
updates every minute. With seconds turned on, it updates every second, and, if iconic, displays a 
second hand. 

-t Test mode — ignore the real time, and instead run in a loop continuously incrementing the time by 
one minute and displaying it. 

clock also accepts all of the generic tool arguments discussed in suntools(l). 

When open, clock listens for keyboard input, toggling its state on four characters: 

s or S toggles the display of seconds. 

t or T toggles the ‘test’ mode. 

SEE ALSO 

suntools(l), date(l) 

FILES 

/usr/lib/fonts/fixedwidthfonts/sail.r.6 

BUGS 

If you reset the system time, clock will not reflect the new time until you change its state open it if 
closed, close it if open. To reset the system time, see date( 1). 

The date display doesn’t go well with the round clock face. 

The clock sometimes freezes. Bringing up the Frame Menu will unstick it. 
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NAME 

cmdtool - Run a shell (or other program) from the SunView text facility 
SYNOPSIS 

cmdtool [ -C ] [ program [ args ] ] 

DESCRIPTION 

cmdtool is a standard tool provided with the SunView environment. 

When invoked, cmdtool runs a program (usually a shell) in a text-based command subwindow. Typed 
characters are inserted at the caret. If this program is a shell, it accepts commands and runs programs in 
the usual way. (See BUGS below). 

Text can be edited anywhere on the command line the same way as in any other text subwindow. Com- 
mands and their output are kept in a log which can be scrolled using the scrollbar. The log file can also be 
edited, or even saved using the Save command in the text facility’s pop-up menu. The Split command, also 
in the pop-up menu, can be used to create two or more independently scrolling views of the log. 

DEFAULTS OPTIONS 

/Tty/Append_only_log 

TRUE is the standard default; it means that only the command line may be editted. FALSE per- 
mits editting of the entire log. See the descripton of Edit On below. 

/Tty/Insert_makes_caret_visible 

This entry describes how hard the command subwindow should try to keep the caret visible. 
Same_as_for_text Is the standard default; it means that the setting for 

Insert_makes_caret_visible will be taken from the Text category instead 
of Tty when a command subwindow is created. 

If_auto_scroll If the caret is showing, and an inserted newline would position it below the 

bottom of the screen as determined by /Text/Lower_context, the text is 
scrolled to keep it showing. The amount scrolled is controlled by 
/Text/Auto_scroll_by. See textedit (1) for more information. 

Always Upon any input action, if the caret is positioned off the screen, it is scrolled 

back into view. 

/Text/Edit_back_char 

Set the character for deleting the character preceding the caret. Note: Stty erase has no effect ; text 
based tools only refer to the defaults database. The standard default is the del key. 

/Text/Edit_back_word 

Set the character for deleting the word preceding the caret Note: Stty werase has no effect-, text 
based tools only refer to the defaults database. The standard default is ctrl-w. 

/Text/Edit_back_line 

Set the character for deleting from the newline preceding the caret to the caret. Note: Stty kill has 
no effect-, text based tools only refer to the defaults database. The standard default is ctrl-u. 

COMMANDLINE OPTIONS 

-C Redirect system console output to this instance of the cmdtool. This will prevent system error 
messages from being printed in unexpected places on the screen. Moreover, since a cmdtool win- 
dow is scrollable, messages that go off the top of the window can be scrolled back for re- 
examination. 

cmdtool also takes generic tool arguments; see suntools (1) for a list of these arguments. 
program [ args ] 

If a program argument is present, cmdtool executes it. Subsequent arguments will be assumed to 
be arguments of the program argument, and will be passed to it for execution. If there are no 
arguments, cmdtool runs the program corresponding to the SHELL environment variable. If this 
environment variable is not available, then cmdtool runs /bin/sh. 
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THE COMMAND SUBWINDOW 

The subwindow of cmdtool is a command subwindow, which is also found in dbxtool and potentially in 
other tools as well. The command subwindow is based on the text facility. For more information about the 
text facility, see Windows and Window-Based Tools: Beginner’s Guide. The pop-up menu associated with 
command subwindow is the same as that for the text facility (see textedit (1)), with one additional item, 
Edit On. The generic text menu items will not be described here except for Put, then Get, as it approxi- 
mates the functionality of Stuff in shelltool (1), and is also implemented for shelltool. 

Put, then Get 

When there is a selection, this item reads Put, then Get. It causes the selection to be copied both 
to the shelf and to the caret. 

Put, then Get 

When there is no selection but there is text on the shelf, Put, then is grayed out, though Get 
remains active. Selecting this item causes the contents of the shelf to be copied to the caret. When 
there is no selection and nothing is on the shelf, this item is inactive. 

Edit On 

If the defaults entry Append_only_log is set to TRUE, but at some point you want to edit the log, 
selecting this menu item makes editting the log possible. When the log is editable, this item reads 
Edit Off, and selecting it makes the log read-only before the start of the command line. 

Certain text facility accelerators that are especially useful in command subwindows are described here. See 
textedit (1) for more information. 

CTRL-RETURN 

Holding down the control key while typing newline (carriage return) positions the caret at the bot- 
tom and scrolls it into view, as determined by the defaults option /Text/Lower_context. 

CTRL-P is an accelerator for the Put, then Get menu item described above. 

CAPS-lock 

Bound to FI, it causes subsequent keyboard input to be uppercase. This key is a toggle; striking it 
a second time undoes the effect of the first strike. 

FILES 

/tmp/tty.txtnnnnnn 
"/.texts wrc 
SEE ALSO 

shelltool(l), suntools(l), textedit(l), defaultsedit(l), 

Windows and Window-Based Tools: Beginner’s Guide 

BUGS 

Full terminal emulation is not yet supported. Programs that use cbreak or raw mode, no echo, or curses 
do not work as expected. Some examples of manifestations of this deficiency include: 

• To send a command to more other than newline, the desired command must be followed by ctrl-d. 

• v/ comes up in open mode. 

• The ~h command in mail doesn’ t work. 

• The password to su is echoed. 

o ctrl-c from a cmdtool running su but not started from a shell owned by root doesn’t work. 

• The select system call never notices input on stdin. 

• rlogin double echos and CTRL-D kills rlogin, not just the program running from it 
Occasionally the program run from cmdtool unexplainably hangs. 
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NAME 

cmp - compare two files 
SYNOPSIS 

cmp [ -1 ] [ -s ] filel file2 
DESCRIPTION 

Cmp compares filel and Jile2. If filel is cmp reads from the standard input. Under default options 
cmp makes no comment if the files are the same; if they differ, it announces the byte and line number at 
which the difference occurred. If one file is an initial subsequence of the other, that fact is noted. 

OPTIONS 

-1 Print the byte number (decimal) and the differing bytes (octal) for each difference. 

-s Print nothing for differing files; return codes only. 

SEE ALSO 

diff(l), comm(l) 

DIAGNOSTICS 

Exit code 0 is returned for identical files, 1 for different files, and 2 for an inaccessible or missing argu- 
ment. 
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NAME 

col - filter reverse paper motions 

SYNOPSIS 

col [ -bfh ] 

DESCRIPTION 

col copies the standard input to the standard output and performs line overlays implied by reverse line 
feeds (ESC-7 in ASCII) and by forward and reverse half line feeds (ESC-9 and ESC-8). col is particularly 
useful for filtering multicolumn output made with the ‘.rt’ command of nr off and output resulting from use 
of the tbl preprocessor. 

The control characters SO (ASCII code 017), and SI (016) are assumed to start and end text in an alternate 
character set. The character set (primary or alternate) associated with each printing character read is 
remembered; on output, SO and SI characters are generated where necessary to maintain the correct treat- 
ment of each character. 

All control characters are removed from the input except space, backspace, tab, return, newline, ESC (033) 
followed by one of 7, 8, 9, SI, SO, and VT (013). This last character is an alternate form of full reverse 
line feed, for compatibility with some other hardware conventions. All other non-printing characters are 
ignored. 

OPTIONS 

-f Fine: although col accepts half line motions in its input, it normally does not emit them on output. 
Instead, text that would appear between lines is moved to the next lower full line boundary. The 
-f option suppresses this treatment — in this case the output from col may contain forward half 
line feeds (ESC-9), but will still never contain either kind of reverse line motion. 

-b col assumes that the output device in use is not capable of backspacing. In this case, if several 
characters are to appear in the same place, only the last one read will be taken. 

-h Convert strings of blanks to tabs (this increases printing time). 

SEE ALSO 

troff(l), tbl(l) 

BUGS 

Can’t back up more than 128 lines. 

No more than 800 characters, including backspaces, on a line. 
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NAME 

colcrt - filter nroff output for CRT previewing 
SYNOPSIS 

colcrt [-] [-2] [file... ] 

DESCRIPTION 

Colcrt provides virtual half-line and reverse line feed sequences for terminals without such capability, and 

on which overstriking is destructive. Half-line characters and underlining (changed to dashing * ") are 

placed on new lines in between the normal output lines. 

OPTIONS 

- Suppress all underlining — especially useful for previewing allboxed tables from tbl(l). 

-2 Print all half-lines, effectively double spacing the output Normally, a minimal space output for- 

mat is used which suppresses empty lines. Colcrt never suppresses two consecutive empty lines, 
however. The -2 option is useful for sending output to the line printer when the output contains 
superscripts and subscripts which would otherwise be invisible. 

EXAMPLE 

A typical use of colcrt would be 

tbl exum2.n | nroff -ms | colcrt - 1 more 

SEE ALSO 

nroff(l), troff(l), col(l), more(l), ul(l) 

BUGS 

Can’t back up more than 102 lines. 

General overstriking is lost; as a special case T overstruck with or underline becomes V. 

Lines are trimmed to 132 characters. 

Some provision should be made for processing superscripts and subscripts in documents which are already 
double-spaced. 
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NAME 

colrm - remove columns from a file 
SYNOPSIS 

colrm [ started [ endcol ] ] 

DESCRIPTION 

Colrm removes selected columns from a text file. The text is is taken from standard input and copied to the 
standard output with the specified columns removed. 

If only started is specified, the columns of each line are removed starting with startcol and extending to 
the end of the line. If both startcol and endcol are specified, all columns between startcol and endcol, 
inclusive, are removed. 

Column numbering starts with column 1. 

SEE ALSO 

expand(l) 
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NAME 

comb - combine SCCS deltas 
SYNOPSIS 

/usr/sccs/comb [ -o ] [ -s ] [ -p SID ] [ -c list ] filename . . . 

DESCRIPTION 

Comb generates a shell procedure (see sh( 1)) which, when run, will reconstruct the given SCCS files. If a 
directory is named, comb behaves as though each file in the directory were specified as a named file, 
except that non-SCCS files (last component of the path name does not begin with s.) and unreadable files 
are silently ignored. If a name of - is given, the standard input is read; each line of the standard input is 
taken to be the name of an SCCS file to be processed; non-SCCS files and unreadable files are silently 
ignored. The generated shell procedure is written on the standard output. 

OPTIONS 

Options are explained as though only one named file is to be processed, but the effects of any option apply 
independently to each named file. 

-p SID The SCCS Identification string (SID) of the oldest delta to be preserved. All older deltas are dis- 
carded in the reconstructed file. 

-c list A list of deltas to be preserved. All other deltas are discarded. See get(l) for the syntax of a list. 

-o For each get -e generated, the reconstructed file is accessed at the release of the delta to be 
created. In the absence of the — o option, the reconstructed file is accessed at the most recent 
ancestor. Use of the -o option may decrease the size of the reconstructed SCCS file. It may also 
alter the shape of the delta tree of the original file. 

-s Generate a shell procedure which, when run, will produce a report giving, for each file: the file 
name, size (in blocks) after combining, original size (also in blocks), and percentage change com- 
puted by: 

100 * (original - combined) / original 

It is recommended that before any SCCS files are actually combined, you should use this option to 
determine exactly how much space is saved by the combining process. 

If no options are specified, comb preserves only leaf deltas and the minimal number of ancestors needed to 
preserve the tree. 

FILES 

s.COMB The name of the reconstructed SCCS file, 

comb????? Temporary. 

SEE ALSO 

sccs(l), admin(l), delta(l), get(l), help(l), prs(l), sccsfile(5). 

Source Code Control System in Programming Tools for the Sun Workstation. 

DIAGNOSTICS 

Use help(\) for explanations. 

BUGS 

Comb may rearrange the shape of the tree of deltas. It may not save any space; in fact, it is possible for the 
reconstructed file to actually be larger than the original. 
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NAME 

comm - select or reject lines common to two sorted files 
SYNOPSIS 

comm [ - [ 123 ] ] filel file2 
DESCRIPTION 

Comm reads filel and file2, which should be ordered in ASCII collating sequence, and produces a three 
column output: lines only in filel; lines only in file2; and lines in both files. The filename means the 
standard input. 

Flags 1, 2, or 3 suppress printing of the corresponding column. Thus comm -12 prints only the lines com- 
mon to the two files; comm -23 prints only lines in the first file but not in the second; comm -123 does 
nothing. 

SEE ALSO 

cmp(l), diff(l), uniq(l) 
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NAME 

compact, uncompact, ccat - compress and uncompress files, and cat them 
SYNOPSIS 

compact [ filename . . . ] 
uncompact [ filename . . . ] 
ccat [ filename ... ] 

DESCRIPTION 

Compact compresses the named files using an adaptive Huffman code. If no file names are given, the stan- 
dard input is compacted to the standard output. Compact operates as an on-line algorithm. Each time a 
byte is read, it is encoded immediately according to the current prefix code. This code is an optimal Huff- 
man code for the set of frequencies seen so far. It is unnecessary to prepend a decoding tree to the 
compressed file since the encoder and the decoder start in the same state and stay synchronized. Further- 
more, compact and uncompact can operate as filters. In particular: 

... | compact | uncompact | . . . 
operates as a (very slow) no-op. 

When an argument file is given, it is compacted and the resulting file is placed in file.C; file is removed. 
The first two bytes of the compacted file code the fact that the file is compacted. This code is used to 
prohibit recompaction. 

The amount of compression to be expected depends on the type of file being compressed. Typical values 
of compression are: Text (38%), Pascal Source (43%), C Source (36%) and Binary (19%). These values 
are the percentages of file bytes reduced. 

Uncompact restores the original file from a file called file.C which was compressed by compact. If no file 
names are given, the standard input is uncompacted to the standard output 

Ccat cats the original file from a file compressed by compact, without uncompressing the file. 

FILES 

*C compacted file created by compact, removed by uncompact 

SEE ALSO 

Gallager, Robert G., Variations on a Theme of Huffman’, I.E.E.E. Transactions on Information Theory, 
vol. IT-24, no. 6, November 1978, pp. 668 - 674. 
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NAME 

cp - copy files 
SYNOPSIS 

cp [ — i ] [ -r ] filel file2 
cp [ -i ] [ -r ] file . . . directory 
DESCRIPTION 

Filel is copied onto file2 . The mode and owner of file2 are preserved if it already existed; the mode of the 
source file is used otherwise. 

In the second form, one or more files are copied into the directory with their original file-names. 

Cp refuses to copy a file onto itself. 

OPTIONS 

-i Interactive: prompt the user with the name of the file whenever the copy would overwrite an old 
file. Answering with ’y’ means that cp should go ahead and copy the file. Any other answer will 
prevent cp from overwriting the file. 

-r Recursive: if any of the source files are directories, cp copies each subtree rooted at that name; in 
this case the destination must be a directory. 

EXAMPLES 

To make a backup copy of goodies : 

% cp goodies old.goodies 

To copy an entire directory hierarchy: 

% cp -r /usr/wendy/src /usr/wendy/backup 

However, BEWARE of a recursive copy like this one: 

% cp -r /usr/wendy/src /usr/wendy/src/backup 
which keeps copying files until it fills the entire file system. 

SEE ALSO 

cat(l), pr(l), mv(l), rcp(lC) 

BUGS 

An option to copy timestamps to the new files — for instance, when copying a whole hierarchy from one 
file system to another file system, or when making a backup copy, would be welcome. 
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NAME 

cpio - copy file archives in and out 

SYNOPSIS 

cpio -o [ acBvs ] 

cpio -i [ Bcdmrtuv6s ] [ patterns ] 
cpio -p [ adlmruvs ] directory 
DESCRIPTION 

cpio -o (copy out) reads the standard input to get a list of pathnames, and then copies those files onto the 
standard output, together with pathname and status information. 

cpio -i (copy in) reads the standard input (which is assumed to be the product of a previous cpio -o com- 
mand), to get a list of files selected by zero or more patterns as defined in the name-generating notation of 
sh or csh. In patterns, the meta-characters ?, *, and [. . .] match the slash (/) character. The default for 
patterns is * (select all files). 

cpio -p (pass) copies out and in in a single operation. Destination pathnames are interpreted relative to the 
named directory. 

OPTIONS 

a Reset the access times of input files after they have been copied. 

B Input/output is to be blocked at 5120 bytes to the record. This does not apply to the pass option. 
This option is only meaningful with data directed to or from /dev/rmt? 

d Directories should be created as needed. 

c Write header information in ASCII character form for portability. 

r Interactively rename files. If the user types a null line, the file is skipped. 

t Print a Table of contents of the input. No files are created. 

u Copy unconditionally . Normally, an older file will not replace a newer file with the same name. 

v Verbose option. A list of filenames is displayed. When used with the t option, the table of con- 

tents looks like the output of an Is -I command (see /s(l)). 

1 Whenever possible, link files rather than copying them. Usable only with the -p option. 

m Retain previous file modification time. This option is ineffective on directories that are being 
copied. 

6 Process an old (version 6 UNIX system) file. This is only useful with -i (copy in), 

s Swaps pairs of data bytes. Note that the s option cannot be used with the c option. 

EXAMPLES 

To copy the contents of a directory into an archive: 

tutorial% Is | cpio -o > /dev/mtO 

To duplicate the olddir directory hierarchy in the newdir directory: 
tutorial% cd olddir 

tutorial% find . -print | cpio -pdl newdir 

Some forms of cpio tapes from other sites have the bytes swapped in the file. The s option doesn’t help 
since it only swaps the data bytes and not the header. To overcome this problem, use dd with the 
conv=swab option to swap all pairs of bytes (including the header), then pipe the output of dd through cpio 
with the s option to swap the data bytes back again: 

tutorial% dd if =filename conv=swab | cpio —is 


Sun Release 3.0 


Last change: 23 September 1985 


51 



CPIO(l) 


USER COMMANDS 


CPIO(l) 


SEE ALSO 

ar(l), find(l), cpio(5), tar(l) 

BUGS 

Pathnames are restricted to 128 characters. If there are too many unique linked files, cpio runs out of 
memory to keep track of them and linking information is lost thereafter. Only the super-user can copy spe- 
cial files. 
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NAME 

cpp - the C language preprocessor 
SYNOPSIS 

/lib/ cpp [ -P ] [ -C ] [ -U name ] [ -D name ] [ -D name=def ] [ -Mr ] [ ifile [ ofile ] ] 

DESCRIPTION 

Cpp is the C language preprocessor which is invoked as the first pass of any C compilation using the cc(l) 
command ( cpp may optionally be invoked as the first pass of a FORTRAN 77 or Pascal compilation — see 
/77(1) orpc(l)). Thus the output of cpp is designed to be in a form acceptable as input to the next pass of 
the compiler. The preferred way to invoke cpp is through the cc(l) command. See m4( 1) for a general 
macro processor. 

Cpp optionally accepts two file names as arguments. Ifile and ofile are respectively the input and output 
for the preprocessor. They default to standard input and standard output if not supplied. 

OPTIONS 

-P Preprocess the input without producing the line control information used by the next pass of the C 
compiler. 

-C Pass all comments (except those which appear on cpp directive lines) through the preprocessor. 
By default, cpp strips out C-style comments. 

-U name 

Remove any initial definition of name, where name is a reserved symbol that is predefined by the 
particular preprocessor. The current list of these possibly reserved symbols includes unix, sun 
and either mc68010 or mc68020 (depending on whether you are running on a Sun-2 or Sun-3 sys- 
tem, respectively). 

— D name 

Define name as 1 (one). This is the same as if a — D name=l option appeared on the cpp command 
line, or as if a #define name 1 line appeared in the source file that cpp is processing. 
-Dname=def 

Define name as if by a #define directive. This is the same as if a #define name def line 
appeared in the source file that cpp is processing. 

-Idir Change the algorithm for searching for #include files whose names do not begin with / to look in 
dir before looking in the directories on the standard list. Thus, #include files whose names are 
enclosed in " " will be searched for first in the directory of the current source file, then in direc- 
tories named in -I options, and last in directories on a standard list. For #include files whose 
names are enclosed in <>, the directory of the ifile argument is not searched. See the section enti- 
tled details below, for exact details of the search order. 

-R Allow recursive macros. 

DIRECTIVES 

All cpp directives start with lines begun by #. White space (blanks or tabs) can appear after the #. The 
directives are: 

#define name token-string 

Replace subsequent instances of name with token-string. 

#define name ( arg, arg ) token-string 

There can be no space between name and the ‘(’. Replace subsequent instances of name followed 
by a ‘(’> a list of comma-separated tokens, and a ‘(’ by token-string where each occurrence of an 
arg in the token-string is replaced by the corresponding token in the comma-separated list. 

#undef name 

Forget the definition of name (if any) from now on. 

#include "filename" 

#include <filename> 
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Include at this point the contents of filename (which is then run through cpp). When the 
<filename> notation is used, filename is only searched for in the standard places. See DETAILS 
below. 

#Iine integer-constant "filename" 

Generate line control information for the next pass of the C compiler. Integer-constant is inter- 
preted as the line number of the next line and filename is interpreted as the file where it comes 
from. If "filename" is not given, the current filename is unchanged. 

#endif comment 

Ends a section of lines begun by a test directive (#if, #ifdef, or #ifndef). Each test directive must 
have a matching #endif. The comment can be used to associate the #endif with its opening #if. 

#ifdef name 

The lines following will appear in the output if and only if name has been the subject of a previous 
#define or a -D option without being the subject of an intervening #undef. 

#ifndef name 

The lines following will not appear in the output if and only if name has been the subject of a pre- 
vious tdefine or a -D option without being the subject of an intervening #undef. 

#if constant-expression 

Lines following will appear in the output if and only if the constant-expression evaluates to 
nonzero. All binary non-assignment C operators, including &&, 1 1, and „ are legal in constant- 
expression. The ?: operator, and the unary -, !, and ' operators, are also legal in constant- 
expression . The precedence of the operators is the same as defined by the C language. There is 
also a unary operator defined, which can be used in constant-expression in these two forms: 
defined ( name ) or defined name. This allows the effect of #ifdef and #ifndef in a #if directive. 
Only these operators, integer constants, and names which are known by cpp should be used in 
constant-expression. In particular, the sizeof operator is not available. 

#else comment 

Reverses for the following lines the notion of the test directive currently in effect. So if lines pre- 
vious to this directive are ignored, the following lines will appear in the output, and vice versa. 
The comment can be used to associate the #else with its opening #if. 

The test directives and corresponding #else directives can be nested. 

DETAILS 

Directory search order for #include files is: 

1. the directory of the file which contains the #include request (that is, #include is relative to the file 
being scanned when the request is made) 

2. the directories specified by -I options, in left-to-right order. 

3. the standard directory(s) ( lusrlinclude for the Sun system). 

Special Names : Two special names are understood by cpp. The name LINE is defined as the 

current line number (a decimal integer) as known by cpp, and FILE is defined as the current 

filename (a C string) as known by cpp. They can be used anywhere (including in macros) just as any other 
defined name. 

A newline terminates a character constant or quoted string. 

An escaped newline (that is, a backslash immediately followed by a newline) may be used in the body 
of a #define statement to continue the definition onto the next line. The escaped newline is not included in 
the macro body. 

Comments are removed (unless the — C option is used on the command line). Comments are also 
ignored, except that a comment terminates a token. 
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Macro formal parameters are recognized in #define bodies even inside character constants and quoted 
strings. The output from: 

#define abc(a) ’\a’ 
abc(xyz) 

is the seven characters ’\xyz’ (space, single-quote, escape character, x, y, z, single-quote). Macro names 
are not recognized inside character constants or quoted strings during the regular scan. Thus: 

#define abc xyz 
printf("abc"); 

does not expand ‘abc’ in the second line, because it is inside a quoted string which is not part of a #define 
macro definition. 

Macros are not expanded while processing a#define or#undef. Thus: 

#define abc bletch 
#define xyz abc 
#undef abc 
xyz 

produces ‘abc’. The token appearing immediately after a#ifdef or #ifndef is not expanded. 

Macros are not expanded during the scan which determines the actual parameters to another macro 
call. Thus: 

#define reverse(first,second)second first 
#define greeting hello 
reverse(greeting, 

#define greeting goodbye 

) 

produces ‘ goodbye’ (and warns about the redefinition of ‘greeting’). 

Output consists of a copy of the input file, with modifications, plus lines of the form: ttlineno "filename " 
— indicating the original source line number and filename of the following output line. 

FILES 

lusr/include standard directory for #include files 

SEE ALSO 

cc(l), m4(l), f77(l), pc(l). 

DIAGNOSTICS 

The error messages produced by cpp are intended to be self-explanatory. The line number and filename 
where the error occurred are printed along with the diagnostic. 

NOTES 

When newline characters were found in argument lists for macros to be expanded, some previous versions 
of cpp put out the newlines as they were found and expanded. The current version of cpp replaces these 
newlines with blanks. 
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NAME 

crypt - encode/decode 

SYNOPSIS 

crypt [ password ] 

DESCRIPTION 

crypt encrypts and decrypts the contents of a file, crypt reads from the standard input and writes on the 
standard output. The password is a key that selects a particular transformation. If no password is given, 
crypt demands a key from the terminal and turns off printing while the key is being typed in. crypt 
encrypts and decrypts with the same key: 

tutorial% crypt key <clear.file >encrypted.file 
tutorial% crypt key <encrypted.file | pr 
will print the contents of clear. file. 

Files encrypted by crypt are compatible with those treated by the editors ed, ex and vi in encryption mode. 

The security of encrypted files depends on three factors: the fundamental method must be hard to solve; 
direct search of the key space must be infeasible; ‘sneak paths’ by which keys or cleartext can become visi- 
ble must be minimized. 

crypt implements a one-rotor machine designed along the lines of the German Enigma, but with a 256- 
element rotor. Methods of attack on such machines are widely known, thus crypt provides minimal secu- 
rity. 

The transformation of a key into the internal settings of the machine is deliberately designed to be expen- 
sive, that is, to take a substantial fraction of a second to compute. However, if keys are restricted to (say) 
three lower-case letters, then encrypted files can be read by expending only a substantial fraction of five 
minutes of machine time. 

Since the key is an argument to the crypt command, it is potentially visible to users executing ps or a 
derivative command. To minimize this possibility, crypt takes care to destroy any record of the key 
immediately upon entry. No doubt the choice of keys and key security are the most vulnerable aspect of 
crypt. 

FILES 

/dev/tty for typed key 
SEE ALSO 

des(l), ed(l), ex(l), makekey(8), vi(l) 

RESTRICTIONS 

This program is not available on software shipped outside the U.S. 
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NAME 

csh - a shell (command interpreter) with C-like syntax 
SYNOPSIS 

csh [ -cefinstvVxX ][arg ... ] 

DESCRIPTION 

csh is a command language interpreter which may be used instead of sh, typically to take advantage of its 
history mechanism (see History Substitutions) and its job control facilities (see Jobs). 

An instance of csh begins by executing commands from the file .cshrc in the user’s home directory. If this 
is a login shell then csh also executes commands from the file .login in the user’s home directory. It is typi- 
cal for users on crt’s to put the command stty crt in their .login file, and call tset from the .login file as 
well. 


In the normal case, the shell then begins reading commands from the terminal, prompting with 1 host- 
name % ’. Processing of arguments and the use of the shell to process files containing command scripts is 
described later. 


The shell then repeatedly performs the following actions: a line of command input is read and broken into 
words. This sequence of words is placed on the command history list and then parsed. Finally each com- 
mand in the current line is executed. 

When a login shell terminates it executes commands from the file .logout in the users home directory. 
Lexical structure 


The shell splits input lines into words at blanks and tabs with the following exceptions: The characters *&’, 
T> ‘>\ ‘(’> and *)’ form separate words. If doubled in *&&’, ‘| |’, *«’, or *»’ these pairs form 

single words. These parser metacharacters may be made part of other words, or prevented their special 
meaning, by preceding them with ‘W A newline preceded by a ‘V is equivalent to a blank. 


In addition strings enclosed in matched pairs of quotations, "’, *' ’ or form parts of a word; metachar- 
acters in these strings, including blanks and tabs, do not form separate words. These quotations have 
semantics to be described subsequently. Within pairs of "’ or characters a newline preceded by a ‘V 
gives a true newline character. 


When the shell’s input is not a terminal, the character *#’ introduces a comment which continues to the end 
of the input line. The *#’ character does not introduce a comment when preceded by ‘V and in quotations 
using*'’, “'’.and"”. 

Commands 


A simple command is a sequence of words, the first of which specifies the command to be executed. 

A simple command or a sequence of simple commands separated by T (vertical bar) characters forms a 
pipeline. The output of each command in a pipeline is connected to the input of the next. Sequences of 
pipelines may be separated by *;’, and are then executed sequentially. A sequence of pipelines may be exe- 
cuted without immediately waiting for it to terminate by following it with an *&’. 

Any of the above may be placed in *(’ *)’ to form a simple command (which may be a component of a 
pipeline, etc.) It is also possible to separate pipelines with *| |’ or *&&’ indicating, as in the C language, 
that the second is to be executed only if the first fails or succeeds respectively. (See Expressions). 

Jobs 

The shell associates a job with each pipeline. It keeps a table of current jobs, which you can display with 
the jobs command, and assigns them small integer numbers. When a job is started asynchronously with 
*&’, the shell prints a line which looks like: 

[1] 1234 
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indicating that this job is job number 1 and has one (top-level) process, whose process id is 1234. 

If you are running a job and wish to do something else you may hit the key A Z (control-Z) which sends a 
STOP signal to the current job. The shell then normally indicates that the job has been ‘Stopped’, and 
displays another prompt. You can then manipulate the state of this job, putting it in the background with 
the bg command, or run some other commands and then eventually bring the job back into the foreground 
with the foreground command fg. A A Z takes effect immediately and is like an interrupt in that pending 
output and unread input are discarded when it is typed. There is another special key A Y which does not 
generate a STOP signal until a program attempts to read (2) it. This can usefully be typed ahead when you 
have prepared some commands for a job which you wish to stop after it has read them. 

A job being run in the background will stop if it tries to read from the terminal. Background jobs are nor- 
mally allowed to produce output, but this can be disabled by giving the command stty tostop. If you set 
this tty option, background jobs will stop when they try to produce output like they do when they try to 
read input. 

There are several ways to refer to jobs in the shell. The character introduces a job name. If you wish 
to refer to job number 1, you can name it as ‘%1’. Just naming a job brings it to the foreground; thus ‘%V 
is a synonym for ‘fg %V, which brings job 1 back into the foreground. Similarly, typing ‘%1 &’ resumes 
job 1 in the background. Jobs can also be named by prefixes of the string typed in to start them, if these 
prefixes are unambiguous; thus, for example, ‘%ex’ normally restarts a suspended ex job, if there is only 
one suspended job whose name begins with the string ‘ex’. It is also possible to use ‘%?string’ to specify a 
job whose text contains string, if there is only one such job. 

The shell maintains a notion of the current and previous jobs. In output pertaining to jobs, the current job 
is marked with a V and the previous job with a The abbreviation ‘%+’ refers to the current job and 
*%-’ refers to the previous job. For close analogy with the syntax of the history mechanism (described 
below), *%%’ is also a synonym for the current job. 

Status reporting 

The shell learns immediately whenever a process changes state. It normally informs you whenever a job 
becomes blocked so that no further progress is possible, but only just before it prints a prompt. This is 
done so that it does not otherwise disturb your work. If, however, you set the shell variable notify, the shell 
will notify you immediately of changes of status in background jobs. There is also a shell command notify 
which marks a single process so that its status changes will be immediately reported. By default notify 
marks the current process; simply say ‘notify’ after starting a background job to mark it. 

When you try to leave the shell while jobs are stopped, you will be warned that ‘You have stopped jobs.’ 
You may use the jobs command to see what they are. If you do this or immediately try to exit again, the 
shell will not warn you a second time, and the suspended jobs will be terminated. 

Substitutions 

We now describe the various transformations the shell performs on the input in the order in which they 
occur. 

History substitutions 

History substitutions place words from previous command input as portions of new commands, making it 
easy to repeat commands, repeat arguments of a previous command in the current command, or fix spelling 
mistakes in the previous command with little typing and a high degree of confidence. History substitutions 
begin with the character “!’ and may begin anywhere in the input stream (with the proviso that they do not 
nest.) This “!’ may be preceded by an ‘V to prevent its special meaning; for convenience, a '!’ is passed 
unchanged when it is followed by a blank, tab, newline, “=’ or ‘(’. History substitutions also occur when 
an input line begins with ‘ A ’ (circumflex) — this special abbreviation is described later. Any input line 
which contains history substitution is echoed on the terminal before it is executed as it could have been 
typed without history substitution. 
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Commands input from the terminal which consist of one or more words are saved on the history list, the 
size of which is controlled by the history variable; the previous command is always retained, regardless of 
its value. The history substitutions reintroduce sequences of words from these saved commands into the 
input stream. Commands are numbered sequentially from 1. 

For definiteness, consider the following output from the history command: 

9 write michael 

10 exwrite.c 

11 cat oldwrite.c 

12 diff *write.c 

The commands are shown with their event numbers. It is not usually necessary to use event numbers, but 
the current event number can be made part of the prompt by placing an ‘ !’ in the prompt string. 

With the current event 13 we can refer to previous events by event number Mil’, relatively as in M-2’ 
(referring to the same event), by a prefix of a command word as in Md’ for event 12 or Mwri’ for event 9, or 
by a string contained in a word in the command as in M?mic?’ also referring to event 9. These forms, 
without further modification, simply reintroduce the words of the specified events, each separated by a sin- 
gle blank. As a special case M!’ refers to the previous command; thus M!’ alone is essentially a redo. 

To select words from an event we can follow the event specification by a and a designator for the 
desired words. The words of an input line are numbered from 0, the first (usually command) word being 0, 
the second word (first argument) being 1, etc. The basic word designators are: 

# the entire command line typed so far 

0 first (command) word 

n n ’th argument 

first argument, that is, ‘1’ 

$ last argument 

% word matched by (immediately preceding) Is ? search 
x-y range of words 

-y abbreviates ‘0 -y ’ 

* abbreviates **-$’, or nothing if only 1 word in event 

x* abbreviates ‘x-$’ 

x - like ‘x * ’ but omitting word *$’ 

The separating the event specification from the word designator can be omitted if the argument selector 
begins with a * A ’, *$’, or After the optional word designator can be placed a sequence of 

modifiers, each preceded by a M’. The following modifiers are defined: 

h Remove a trailing pathname component, leaving the head, 

r Remove a trailing ‘.xxx’ component, leaving the root name, 

e Remove all but the extension ‘.xxx’ part. 

s/l/rl Substitute r for / 

t Remove all leading pathname components, leaving the tail. 

& Repeat the previous substitution. 

g Apply the change globally, prefixing the above, for example, ‘g&’. 

p Print the new command but do not execute it. 

q Quote the substituted words, preventing further substitutions, 

x Like q, but break into words at blanks, tabs and newlines. 

Unless preceded by a ‘g’ the modification is applied only to the first modifiable word. With substitutions, it 
is an error for no word to be applicable. 

The left hand side of substitutions are not regular expressions in the sense of the editors, but rather strings. 
Any character may be used as the delimiter in place of 7’; a V quotes the delimiter into the l and r strings. 
The character *&’ in the right hand side is replaced by the text from the left A ‘V quotes *&’ also. A null l 
uses the previous string either from a / or from a contextual scan string s in M Is ?’. The trailing delimiter in 
the substitution may be omitted if a newline follows immediately as may the trailing '?’ in a contextual 
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scan. 

A history reference may be given without an event specification, for example, In this case the refer- 
ence is to the previous command unless a previous history reference occurred on the same line in which 
case this form repeats the previous reference. Thus ‘!?foo?“ !$’ gives the first and last arguments from the 
command matching ‘?foo?’. 

A special abbreviation of a history reference occurs when the first non-blank character of an input line is a 
This is equivalent to ‘!:s A ’ providing a convenient shorthand for substitutions on the text of the previ- 
ous line. Thus ‘ A lb A lib’ fixes the spelling of ‘lib’ in the previous command. Finally, a history substitution 
may be surrounded with and *}’ if necessary to insulate it from the characters which follow. Thus, after 
‘Is -Id 'paul’ we might do ‘!{l}a’ to do ‘Is -Id 'paula’, while ‘!la’ would look for a command starting ‘la’. 

Quotations with ' and " 

The quotation of strings by "’ and ‘"’ can be used to prevent all or some of the remaining substitutions. 
Strings enclosed in "’ are prevented any further interpretation. Strings enclosed in are yet variable and 
command expanded as described below. 

In both cases the resulting text becomes (all or part of) a single word; only in one special case (see Com- 
mand Substitution below) does a ‘"’ quoted string yield parts of more than one word; "’ quoted strings 
never do. 

Alias substitution 

The shell maintains a list of aliases which can be established, displayed and modified by the alias and 
unalias commands. After a command line is scanned, it is parsed into distinct commands and the first word 
of each command, left-to-right, is checked to see if it has an alias. If it does, the text which is the alias for 
that command is reread with the history mechanism available as though that command were the previous 
input line. The resulting words replace the command and argument list. If no reference is made to the his- 
tory list, the argument list is left unchanged. 

Thus if the alias for ‘Is’ is ‘Is -1’ the command ‘Is /usr’ would map to ‘Is -1 /usr’, the argument list here 
being undisturbed. Similarly if the alias for ‘lookup’ was ‘grep ! A /etc/passwd’, ‘lookup bill’ would map to 
‘grep bill /etc/passwd’. 

If an alias is found, the word transformation of the input text is performed and the aliasing process begins 
again on the reformed input line. Looping is prevented if the first word of the new text is the same as the 
old by flagging it to prevent further aliasing. Other loops are detected and cause an error. 

Note that the mechanism allows aliases to introduce parser metasyntax. Thus we can ‘alias print 'pr \!* | 
lpr'’ to make a command which pr’ s its arguments to the line printer. 

Variable substitution 

The shell maintains a set of variables, each of which has as value a list of zero or more words. Some of 
these variables are set by the shell or referred to by it For instance, the argv variable is an image of the 
shell’s argument list, and words of this variable’s value are referred to in special ways. 

Values of variables may be displayed and changed by using the set and unset commands. Of the variables 
referred to by the shell a number are toggles; the shell does not care what their value is, only whether they 
are set or not. For instance, the verbose variable is a toggle which causes command input to be echoed. 
The setting of this variable results from the -v command line option. 

Other operations treat variables numerically. The ‘@’ command permits numeric calculations to be per- 
formed and the result assigned to a variable. Variable values are, however, always represented as (zero or 
more) strings. For the puiposes of numeric operations, the null string is considered to be zero, and the 
second and subsequent words of multiword values are ignored. 

After the input line is aliased and parsed, and before each command is executed, variable substitution is 
performed keyed by *$’ characters. This expansion can be prevented by preceding the *$’ with a ‘V except 
within ‘"’s where it always occurs, and within ‘"s where it never occurs. Strings quoted by " ’ are inter- 
preted later (see Command substitution below) so ‘$’ substitution does not occur there until later, if at all. 
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A *$’ is passed unchanged if followed by a blank, tab, or end-of-line. 

Input/output redirections are recognized before variable expansion, and are variable expanded separately. 
Otherwise, the command name and entire argument list are expanded together. It is thus possible for the 
first (command) word to this point to generate more than one word, the first of which becomes the com- 
mand name, and the rest of which become arguments. 

Unless enclosed in or given the ‘:q’ modifier the results of variable substitution may eventually be com- 
mand and filename substituted. Within a variable whose value consists of multiple words expands to a 
(portion of) a single word, with the words of the variables value separated by blanks. When the ‘:q’ 
modifier is applied to a substitution the variable expands to multiple words with each word separated by a 
blank and quoted to prevent later command or filename substitution. 

The following metasequences are provided for introducing variable values into the shell input Except as 
noted, it is an error to reference a variable which is not set. 

$name 

${name} 

Are replaced by the words of the value of variable name, each separated by a blank. Braces insulate 
name from following characters which would otherwise be part of it. Shell variables have names 
consisting of up to 20 letters and digits starting with a letter. The underscore character is considered 
a letter. 

If name is not a shell variable, but is set in the environment, that value is returned (but : modifiers 
and the other forms given below are not available in this case). 

$name[selector] 

${name[selector]} 

May be used to select only some of the words from the value of name. The selector is subjected to 
“$’ substitution and may consist of a single number or two numbers separated by a The first 
word of a variables value is numbered ‘1’. If the first number of a range is omitted it defaults to T. 
If the last member of a range is omitted it defaults to ‘$#name’. The selector selects all words. It 
is not an error for a range to be empty if the second argument is omitted or in range. 

$#name 

${#name} 

Gives the number of words in the variable. This is useful for later use in a ‘[selector]’. 

$0 

Substitutes the name of the file from which command input is being read. An error occurs if the 
name is not known. 

$number 
$ {number} 

Equivalent to ‘$argv[number]\ 

$* 

Equivalent to ‘$argv[*]\ 

The modifiers ‘:h’, ‘:t’, ‘:r’, ‘:q’ and ‘:x’ may be applied to the substitutions above as may ‘:gh’, ‘:gt’ and 
‘:gr’. If braces ’}’ appear in the command form then the modifiers must appear within file braces. 

The current implementation allows only one modifier on each *$’ expansion. 

The following substitutions may not be modified with modifiers. 

$?name 

${?name} 

Substitutes the string ‘1’ if name is set, ‘0’ if it is not. 

$?0 

Substitutes ‘1’ if the current input filename is known, ‘O’ if it is not. 
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$$ 

Substitute the (decimal) process number of the (parent) shell. 

$< 

Substitutes a line from the standard input, with no further interpretation thereafter. It can be used to 
read from the keyboard in a shell script. 

Command and filename substitution 

The remaining substitutions, command and filename substitution, are applied selectively to the arguments 
of builtin commands. This means that portions of expressions which are not evaluated are not subjected to 
these expansions. For commands which are not internal to the shell, the command name is substituted 
separately from the argument list. This occurs very late, after input-output redirection is performed, and in 
a child of the main shell. 

Command substitution 

Command substitution is indicated by a command enclosed in *' ’. The standard output from such a com- 
mand (but not the diagnostic output) is normally broken into separate words at blanks, tabs and newlines, 
with null words being discarded, this text then replacing the original string. Within ‘"’s, only newlines 
force new words; blanks and tabs are preserved. 

In any case, the single final newline does not force a new word. Note that it is thus possible for a command 
substitution to yield only part of a word, even if the command outputs a complete line. 

Filename substitution 

If a word contains any of the characters ‘*\ *?’, *[’ or ‘{’ or begins with the character “’, that word is a 
candidate for filename substitution, also known as ‘globbing’. This word is then regarded as a pattern, and 
replaced with an alphabetically sorted list of file names which match the pattern. In a list of words specify- 
ing filename substitution it is an error for no pattern to match an existing file name, but it is not required for 
each pattern to match. Only the metacharacters T and T imply pattern matching, the characters “’ 
and ‘{’ being more akin to abbreviations. 

In matching filenames, the character V at the beginning of a filename or immediately following a 7’, as 
well as the character 7’ must be matched explicitly. The character matches any string of characters, 
including the null string. The character *?’ matches any single character. The sequence ‘ [...]’ matches any 
one of the characters enclosed. Within ‘[...]\ a pair of characters separated by matches any character 
lexically between the two. 

The character at the beginning of a filename is used to refer to home directories. Standing alone — that 
is, — it expands to the invoker’s home directory as reflected in the value of the variable home. When 
followed by a name consisting of letters, digits and characters the shell searches for a user with that 
name and substitutes their home directory; thus ‘”ken’ might expand to 7usr/ken’ and ‘”ken/chmach’ to 
7usr/ken/chmach’. If the character is followed by a character other than a letter or 7’ or appears not at 
the beginning of a word, it is left undisturbed. 

The metanotation ‘a{b,c,d}e’ is a shorthand for ‘abe ace ade’. Left to right order is preserved, with results 
of matches being sorted separately at a low level to preserve this order. This construct may be nested. 
Thus l 'source/sl/{oldls,ls}.c’ expands to 7usr/source/sl/oldls.c /usr/source/sl/ls.c’ whether or not these 
files exist without any chance of error if the home directory for ‘source’ is ‘/usr/ source . Similarly 
‘../{memo,*box}’ might expand to ‘../memo ../box ../mbox’. (Note that ‘memo’ was not sorted with the 
results of matching ‘*box’.) As a special case ‘{\ *}’ and *{}’ are passed undisturbed. 

Input/output 

The standard input and standard output of a command may be redirected with the following syntax: 

< name 

Open file name (which is first variable, command and filename expanded) as the standard input. 
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« word 

Read the shell input up to a line which is identical to word. Word is not subjected to variable, 
filename or command substitution, and each input line is compared to word before any substitutions 
are done on this input line. Unless a quoting ‘V, *'* or ‘ v ’ appears in word variable and com- 

mand substitution is performed on the intervening lines, allowing ‘V to quote ‘$\ V and Com- 
mands which are substituted have all blanks, tabs, and newlines preserved, except for the final new- 
line which is dropped. The resultant text is placed in an anonymous temporary file which is given to 
the command as standard input. 

>name 
>! name 
>& name 
>&! name 

The file name is used as standard output. If the file does not exist, it is created. If the file exists, it is 
truncated; its previous contents are lost 

If the variable noclobber is set, the file must not exist or be a character special file (for example, a 
terminal or ‘/dev/null’) or an error results. This helps prevent accidental destruction of files. In this 
case the M’ forms can be used and suppress this check. 

The forms involving *&’ route the diagnostic output into the specified file as well as the standard out- 
put. Name is expanded in the same way as “<’ input filenames are. 

» name 
»& name 
»! name 
»&! name 

Uses file name as standard output like V but places output at the end of the file. If the variable 
noclobber is set, it is an error for the file not to exist unless one of the T forms is given. Otherwise 
similar to V. 

A command receives the environment in which the shell was invoked as modified by the input-output 
parameters and the presence of the command in a pipeline. Thus, unlike some previous shells, commands 
run from a file of shell commands have no access to the text of the commands by default; rather they 
receive the original standard input of the shell. The ‘«’ mechanism should be used to present inline data. 
This permits shell command scripts to function as components of pipelines and allows the shell to block 
read its input Note that the default standard input for a command run detached is not modified to be the 
empty file ‘/dev/null’ ; rather the standard input remains as the original standard input of the shell. If this is 
a terminal and if the process attempts to read from the terminal, the process blocks and the user is notified 
(see Jobs above.) 

Diagnostic output may be directed through a pipe with the standard output. Simply use the form ‘| &’ 
rather than just ‘|\ 

Expressions 


A number of the builtin commands (to be described subsequently) take expressions, in which the operators 
are similar to those of C, with the same precedence. These expressions appear in the @, exit, if, and while 
commands. The following operators are available: 

| | && | "&==!==' !”<=>=<>«» + -*/ % ! " ( ) 


Here the precedence increases to the right, ‘==’ *!=’ ‘="’ and T\ “<=’ ‘>=’ *<’ and V, *«’ and *»’, V 
and 7’ and *%’ being, in groups, at the same level. The “==’ ‘!=’ ‘=" and T’ operators compare 

their arguments as strings; all others operate on numbers. The operators *="’ and T’ are like ‘==’ and *!=’ 
except that the right hand side is a pattern (containing, for example, ‘*’s, ‘?’s and instances of *[...]’) 
against which the left hand operand is matched. This reduces the need for use of the switch statement in 
shell scripts when all that is really needed is pattern matching. 
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Strings which begin with ‘0’ are considered octal numbers. Null or missing arguments are considered ‘O’. 

The result of aU expressions are strings, which represent decimal numbers. It is important to note that no 
two components of an expression can appear in the same word; except when adjacent to components of 
expressions which are syntactically significant to the parser (“&’ T *<’ V ‘(’ “)’) they should be sur- 
rounded by spaces. Variables whose names appear in expressions must have their names preceded by a 
dollar ( $ ) sign, for example: 

@ grab = $grab + 2 

Also available in expressions as primitive operands are command executions enclosed in ‘{’ and *}’ and 
file enquiries of the form *-/ name’ where / is one of: 

r read access 

w write access 

x execute access 

e existence 

o ownership 

z zero size 

f plain file 

d directory 

The specified name is command and filename expanded and then tested to see if it has the specified rela- 
tionship to the real user. If the file does not exist or is inaccessible then all enquiries return false, that is, 
‘O’. Command executions succeed, returning true, that is, ‘1’, if the command exits with status 0, other- 
wise they fail, returning false, that is, ‘O’. If more detailed status information is required, the command 
should be executed outside of an expression and the variable status examined. 

Control flow 

The shell contains a number of commands which can be used to regulate the flow of control in command 
files (shell scripts) and (in limited but useful ways) from terminal input These commands all operate by 
forcing the shell to reread or skip in its input and, due to the implementation, restrict the placement of some 
of the commands. 

The foreach, switch, and while statements, as well as the if-then-else form of the if statement require that 
the major keywords appear in a single simple command on an input line as shown below. 

If the shell’s input is not seekable, the shell buffers up input whenever a loop is being read and performs 
seeks in this internal buffer to accomplish the rereading implied by the loop. (To the extent that this 
allows, backward goto’s will succeed on non-seekable inputs.) 

Builtin commands 

Builtin commands are executed within the shell. If a builtin command occurs as any component of a pipe- 
line except the last, it is executed in a subshell. 

alias 

alias name 
alias name wordlist 

The first form prints all aliases. The second form prints the alias for name. The final form assigns 
the specified wordlist as the alias of name ; wordlist is command and filename substituted. Name is 
not allowed to be alias or unalias. Putting single quote signs (apostrophes) around wordlist and plac- 
ing a \ character in front of any *!’ signs in wordlist often solves any obscure problems with aliases. 

alloc 

Shows the amount of dynamic core in use, broken down into used and free core, and address of the 
last location in the heap. With an argument shows each used and free block on the internal dynamic 
memory chain indicating its address, size, and whether it is used or free. This is a debugging com- 
mand and may not work in production versions of the shell; it requires a modified version of the sys- 
tem memory allocator. 
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bg 

bg %job ... 

Puts the current or specified jobs into the background, continuing them if they were stopped. 

break 

Resumes execution after the end of the nearest enclosing foreach or while. The remaining com- 
mands on the current line are executed. Multi-level breaks are thus possible by writing them all on 
one line. 

breaksw 

Breaks from a switch, resuming after the endsw. 
case label: 

A label in a switch statement as discussed below, 
cd 

cd name 
chdir 

cfadir name 

Change the shell’s working directory to directory name. If no argument is given, change to the home 
directory of the user. 

If name is not found as a subdirectory of the current directory (and does not begin with 7\ ‘J’ or 
each component of the variable cdpath is checked to see if it has a subdirectory name. Finally, 
if all else fails but name is a shell variable whose value begins with 7’, this is tried to see if it is a 
directory. 

continue 

Continue execution of the nearest enclosing while or foreach. The rest of the commands on the 
current line are executed. 

default: 

Labels the default case in a switch statement The default should come after all case labels. 

dirs 
dirs -1 

Prints the directory stack; the top of the stack is at the left, the first directory in the stack being the 
current directory. The second form produces an unabbreviated printout; use of the notation is 
suppressed. 

echo wordlist 
echo -n wordlist 

The specified words are written to the shell’s standard output, separated by spaces, and terminated 
with a newline unless the -n option is specified. 

else 

end 

endif 

endsw 

See the description of the foreach, if, switch, and while statements below, 
eval arg ... 

(As in sh.) The arguments are read as input to the shell and the resulting command(s) executed. 
This is usually used to execute commands generated as the result of command or variable substitu- 
tion, since parsing occurs before these substitutions. See tset{\) for an example of using eval. 

exec command 

The specified command is executed in place of the current shell. 
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exit 

exit(expr) 

The shell exits either with the value of the status variable (first form) or with the value of the 
specified expr (second form). 

fg 

fg %job ... 

Brings the current or specified jobs into the foreground, continuing them if they were stopped, 
foreach name (wordlist) 

end 

The variable name is successively set to each member of wordlist and the sequence of commands 
between this command and the matching end are executed. (Both foreach and end must appear alone 
on separate lines.) 

The builtin command continue may be used to continue the loop prematurely and the builtin com- 
mand break to terminate it prematurely. When this command is read from the terminal, the loop is 
read up once prompting with *?’ before any statements in the loop are executed. If you make a mis- 
take typing in a loop at the terminal you can rub it out 

glob wordlist 

Like echo but no ‘V escapes are recognized and words are delimited by null characters in the output. 
Useful for programs which wish to use the shell to filename expand a list of words. 

goto word 

The specified word is filename and command expanded to yield a string of the form ‘label’. The 
shell rewinds its input as much as possible and searches for a line of the form ‘label:’ possibly pre- 
ceded by blanks or tabs. Execution continues after the specified line. 

hashstat 

Print a statistics line indicating how effective the internal hash table has been at locating commands 
(and avoiding exec’s). An exec is attempted for each component of the path where the hash function 
indicates a possible hit, and in each component which does not begin with a 7’. 

history 
history n 
history -r n 
history -h n 

Displays the history event list; if n is given, display only the n most recent events. The -r option 
reverses the order of printout to be most recent first rather than oldest first The -h option means 
display the history list without leading numbers. This is used to produce files suitable for sourcing 
using the -h option to source. 

if (expr) command 

If the specified expression evaluates true, the single command with arguments is executed. Variable 
substitution on command happens early, at the same time it does for the rest of the if command. 
Command must be a simple command, not a pipeline, a command list, or a parenthesized command 
list. Input/output redirection occurs even if expr is false, when command is not executed (this is a 
bug). 

if (expr) then 
else if (expf2) then 


else 
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endif 

If the specified expr is true, the commands to the first else are executed; else if expr2 is true, the 
commands to the second else are executed, etc. Any number of else-if pairs are possible; only one 
endif is needed. The else part is likewise optional. (The words else and endif must appear at the 
beginning of input lines; the i/ must appear alone on its input line or after an else.) 

jobs 
jobs -1 

Lists the active jobs; given the -1 options lists process id’s in addition to the normal information, 
kill %job 
kill -sig %job ... 
kill pid 

kill -sig pid ... 
kill -1 

Sends either the TERM (terminate) signal or the specified signal to the specified jobs or processes. 
Signals are either given by number or by names (as given in l usrlincludel signal. h, stripped of the 
prefix “SIG”). The signal names are listed by “kill -1”. There is no default, saying just ‘kill’ does 
not send a signal to the current job. If the signal being sent is TERM (terminate) or HUP (hangup), 
then the job or process is sent a CONT (continue) signal as well. 

limit 

limit resource 

limit resource maximum-use 

Limits the consumption by the current process and each process it creates to not individually exceed 
maximum-use on the specified resource. If no maximum-use is given, the current limit is printed; if 
no resource is given, all limitations are given. 

Resources controllable currently include cputime (the maximum number of cpu-seconds to be used 
by each process), filesize (the largest single file which can be created), datasize (the maximum 
growth of the data+stack region via sbrk{ 2) beyond the end of the program text), stacksize (the max- 
imum size of the automatically-extended stack region), and coredumpsize (the size of the largest core 
dump that will be created). 

The maximum-use may be given as a (floating point or integer) number followed by a scale factor. 
For all limits other than cputime the default scale is ‘k’ or ‘kilobytes’ (1024 bytes); a scale factor of 
‘m’ or ‘megabytes’ may also be used. For cputime the default scaling is ‘seconds’, while ‘m’ for 
minutes or ‘h’ for hours, or a time of the form ‘mm:ss’ giving minutes and seconds may be used. 

For both resource names and scale factors, unambiguous prefixes of the names suffice. 

login 

Terminate a login shell, replacing it with an instance of /bin/login. This is one way to log off, 
included for compatibility with sh . 

logout 

Terminate a login shell. Especially useful if ignoreeof is set. 

nice 

nice +number 

nice command 

nice +number command 

The first form sets the nice for this shell to 4. The second form sets the nice to the given number. 
The final two forms run command at priority 4 and number respectively. The super-user may specify 
negative niceness by using ‘nice -number ...’. Command is always executed in a sub-shell, and the 
restrictions placed on commands in simple if statements apply. 

nohup 
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nohup command 

The first form can be used in shell scripts to cause hangups to be ignored for the remainder of the 
script. The second form runs the specified command with hangups ignored. All processes detached 
with *&’ are effectively nohup’ ed. 

notify 

notify %job ... 

Notify the user asynchronously when the status of the current or specified jobs changes; normally 
notification is presented before a prompt. This is automatic if the shell variable notify is set 

onintr 
onintr - 
onintr label 

Control the action of the shell on interrupts. The first form restores the default action of the shell on 
interrupts (terminates shell scripts and returns to the terminal command input level). The second 
form ‘onintr ignores all interrupts. The final form makes the shell execute a ‘goto label’ when an 
interrupt is received or a child process terminates because it was interrupted. 

In any case, if the shell is running detached and interrupts are being ignored, all forms of onintr have 
no meaning and interrupts continue to be ignored by the shell and all invoked commands. 

popd 
popd +n 

Pops the directory stack, returning to the new top directory. With an argument ‘+n’ discards the nth 
entry in the stack. The elements of the directory stack are numbered from 0 starting at the top. 

pushd 
pushd name 
pushd +n 

With no arguments, pushd exchanges the top two elements of the directory stack. Given a name 
argument, pushd changes to the new directory (as in cd) and pushes the old current working directory 
(as in cwd) onto the directory stack. With a numeric argument, rotates the nth argument of the direc- 
tory stack around to be the top element and changes to it The members of the directory stack are 
numbered from the top starting at 0. 

rehash 

Recompute the internal hash table of the contents of the directories in the path variable. This is 
needed if new commands are added to directories in the path while you are logged in. This should 
only be necessary if you add commands to one of your own directories, or if a systems programmer 
changes the contents of one of the system directories. 

repeat count command 

The specified command which is subject to the same restrictions as the command in the one line if 
statement above, is executed count times. I/O redirections occur exactly once, even if count is 0. 

set 

set name 
set name=word 
set name [index] = word 
set name=(wordlist) 

The first form of the command shows the value of all shell variables. Variables which have other 
than a single word as value print as a parenthesized word list. The second form sets name to the null 
string. The third form sets name to the single word. The fourth form sets the index’ th component of 
name to word; this component must already exist The final form sets name to the list of words in 
wordlist. In all cases the value is command and filename expanded. 

These arguments may be repeated to set multiple values in a single set command. Note however, 
that variable expansion happens for all arguments before any setting occurs. 


68 


Last change: 15 November 1985 


Sun Release 3.0 



CSH(l) 


USER COMMANDS 


CSH(l) 


setenv name value 

Sets the value of environment variable name to be value, a single string. The most commonly used 
environment variables, USER, TERM, and PATH, are automatically imported to and exported from 
the csh variables user, term, and path; there is no need to use setenv for these. 

shift 

shift variable 

The members of argv are shifted to the left, discarding argvfl ]. It is an error for argv not to be set or 
to have less than one word as value. The second form performs the same function on the specified 
variable. 

source name 
source -h name 

The shell reads commands from name. Source commands may be nested; if they are nested too dee- 
ply the shell may run out of file descriptors. An error in a source at any level terminates all nested 
source commands. Normally, input during source commands is not placed on the history list; the -h 
option places the commands in the history list without being executed. 

stop 

stop %job ... 

Stops the current or specified job which is executing in the background, 
suspend 

Stops the shell in its tracks, much as if it had been sent a stop signal with “Z. This is most often used 
to stop shells started by su. 

switch (string) 
case strl: 

breaksw 

default: 

breaksw 

endsw 

Each case label is successively matched, against the specified string which is first command and 
filename expanded. The file metacharacters **’, “?’ and “[...]’ may be used in the case labels, which 
are variable expanded. If none of the labels match before a ‘default’ label is found, execution begins 
after the default label. Each case label and the default label must appear at the beginning of a line. 
The command breaksw continues execution after the endsw. Otherwise control may fall through 
case labels and default labels as in C. If no label matches and there is no default, execution contin- 
ues after the endsw. 

time 

time command 

With no argument, a summary of time used by this shell and its children is printed. If arguments are 
given the specified simple command is timed and a time summary as described under the time vari- 
able is printed. If necessary, an extra shell is created to print the time statistic when the command 
completes. 

umask 
umask value 

The file creation mask is displayed (first form) or set to the specified value (second form). The mask 
is given in octal. Common values for the mask are 002 giving all access to the group and read and 
execute access to others or 022 giving all access except no write access for users in the group or oth- 
ers. 
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unalias pattern 

All aliases whose names match the specified pattern are discarded. Thus all aliases are removed by 
‘unalias It is not an error for nothing to be unaliased. 

unhash 

Use of the internal hash table to speed location of executed programs is disabled. 

unlimit resource 
unlimit 

Removes the limitation on resource. If no resource is specified, all resource limitations are 
removed. 

unset pattern 

All variables whose names match the specified pattern are removed. Thus all variables are removed 
by ‘unset this has noticeably distasteful side-effects. It is not an error for nothing to be unset. 

unsetenv pattern 

Removes all variables whose name match the specified pattern from the environment. See also the 
setenv command above and printenv( 1). 

wait 

All background jobs are waited for. It the shell is interactive, an interrupt can disrupt the wait, at 
which time the shell prints names and job numbers of all jobs known to be outstanding. 

while (expr) 
end 

While the specified expression evaluates non-zero, the commands between the while and the match- 
ing end are evaluated. Break and continue may be used to terminate or continue the loop prema- 
turely. (The while and end must appear alone on their input lines.) Prompting occurs here the first 
time through the loop as for the foreach statement if the source of input is a terminal. 

%job 

Brings the specified job into the foreground. 

%job & 

Continues the specified job in the background. 

@ 

@ name = expr 
@ name[index] = expr 

The first form prints the values of all the shell variables. The second form sets the specified name to 
the value of expr. If the expression contains *<’, *>’, or T then at least this part of the expres- 
sion must be placed within ‘(’ *)’. The third form assigns the value of expr to the index’ th argument 
of name. Both name and its index' th component must already exist. 

The operators ‘*=’, *+=’, etc are available as in C. The space separating the name from the assign- 
ment operator is optional. Spaces are, however, mandatory in separating components of expr which 
would otherwise be single words. 

Special postfix *++’ and ‘ — ’ operators increment and decrement name respectively, that is, ‘@ 
i++’. 

Note that there must be a space after the ‘@’ sign. 

Pre-defined and environment variables 

The following variables have special meaning to the shell. Of these, argv, cwd, home, path, prompt, shell 
and status are always set by the shell. Except for cwd and status this setting occurs only at initialization; 
these variables will not then be modified unless this is done explicitly by the user. 
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This shell copies the environment variable USER into the variable user, TERM into term, and HOME into 
home, and copies these back into the environment whenever the normal shell variables are reset The 
environment variable PATH is similarly handled; it is only necessary to worry about its setting in the file 
.cshrc, as inferior csh processes will import the definition of path from the environment and re-export it if 
you then change it. It could be set once in the .login except that commands through the network would not 
see the definition. 


argv 

cdpath 

cwd 

echo 

hardpaths 

histchars 

history 

home 

ignoreeof 

mail 


noclobber 


noglob 


nonomatch 


notify 


Set to the arguments to the shell. Positional parameters are substituted from this vari- 
able: ‘$1’ is replaced by ‘$argv[l]’ ( etc. 

Gives a list of alternate directories searched to find subdirectories in chdir commands. 

The full pathname of the current directory. If the variable hardpaths is set, cwd is 
resolved to contain a pathname with no embedded symbolic link components. 

Set when the -x command line option is given. Echoes each command and its argu- 
ments just before execution. For non-builtin commands all expansions occur before 
echoing. Builtin commands are echoed before command and filename substitution, 
since these substitutions are then done selectively. 

If set, the paths contained in the cwd variable and printed by the cd, chdir, dirs, popd, 
and pushd commands are resolved to contain no symbolic link components. 

Can be given a string value to change the characters used in history substitution. The 
first character of its value is used as the history substitution character, replacing the 
default character !. The second character of its value replaces the character t in quick 
substitutions. 

Can be given a numeric value to control the size of the history list. Any command 
which has been referenced in this many events will not be discarded. If you use an 
overly-large value for history, the shell may run out of memory. The last executed com- 
mand is always saved on the history list. 

The home directory of the invoker, initialized from the environment. The filename 
expansion of refers to this variable. 

If set, the shell ignores end-of-file signals from terminals. This prevents shells from 
being accidentally killed by control-D’s. 

The files where the shell checks for mail. This is done after each command completion 
which will result in a prompt, if a specified interval has elapsed. The shell says ‘You 
have new mail’ if the file exists with an access time not greater than its modify time. 

If the first word of the value of mail is numeric it specifies a different mail checking 
interval, in seconds, than the default, which is 5 minutes. 

If multiple mail files are specified, the shell says ‘New mail in name ’ when there is mail 
in the file name. 

As described in the section on Input/output, restrictions are placed on output redirection 
to insure that files are not accidentally destroyed, and that *»’ redirections refer to 
existing files. 

If set, filename expansion is inhibited. This is most useful in shell scripts which are not 
dealing with filenames, or after a list of filenames has been obtained and further expan- 
sions are not desirable. 

If set, it is not an error for a filename expansion to not match any existing files; rather the 
primitive pattern is returned. It is still an error for the primitive pattern to be malformed, 
that is, ‘echo [’ still gives an error. 

If set, the shell notifies asynchronously of job completions. The default is to rather 
present job completions just before printing a prompt. 
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path 


prompt 


savehist 


shell 


status 


time 


Each word of the path variable specifies a directory in which commands are to he sought 
for execution. A null word specifies the current directory. If there is no path variable, 
only full path names will execute. The usual search path is V, ‘/bin’ and ‘/usr/bin’, but 
this may vary from system to system. For the super-user the default search path is ‘/etc’, 
‘/bin’ and ‘/usr/bin’. A shell which is given neither the -c nor the -t option will nor- 
mally hash the contents of the directories in the path variable after reading .cshrc, and 
each time the path variable is reset. If new commands are added to these directories 
while the shell is active, it may be necessary to give the rehash or the commands may 
not be found. 

The string which is printed before each command is read from an interactive terminal 
input. Subshells are non-interactive, and therefore their prompt variable is unset For 
this reason, and because subshells read the .cshrc file upon being spawned, if is some- 
times convenient to collect aliases and other commands which do not need to be exe- 
cuted by subshells at the end of the ‘.cshrc’ file, and to precede them by the test: 
if ($?prompt == 0) then 
exit 

endif 

If a “!’ appears in the prompt string it is replaced by the current event number unless a 
preceding ‘\’ is given. Default is or ‘# ’ for the super-user. 

is given a numeric value to control the number of entries of the history list that are saved 
in "/.history when the user logs out. Any command which has been referenced in this 
many events will be saved. During start up the shell sources '/.history into the history 
list enabling history to be saved across logins. Overly-large values of savehist will slow 
down the shell during start up. 

The file in which the shell resides. This is used in forking shells to interpret files which 
have execute bits set, but which are not executable by the system. (See the description 
of Non-builtin Command Execution below.) Initialized to the (system-dependent) home 
of the shell. 

The status returned by the last command. If it terminated abnormally, then 0200 is 
added to the status. Builtin commands which fail return exit status ‘T, all other builtin 
commands set status ‘O’. 

Controls automatic timing of commands. The time variable can be supplied with one or 
two values, such as ‘set time=3’ or ‘set time=(3 "%E %P")’. The first value is a number 
— n for instance. The shell displays a resource-usage summary for any command run- 
ning for more than n CPU seconds. The second value is optional and is a character 
string which determines which resources the user wishes displayed. The character string 
can be any string of text with embedded control key-letters in it. A control key-letter is 
a percent sign ( % ) followed by a single upper-case letter. Unrecognized key-letters are 
simply printed. The control key-letters are: 

D Average amount of unshared data space used in Kilobytes. 

E Elapsed (wallclock) time for the command. 

F Page faults. 

I Number of block input operations. 

K Average amount of unshared stack space used in Kilobytes. 

M Maximum real memory used during execution of the process. 

O Number of block output operations . 

P Total CPU time — U (user) plus S (system) — as a percentage of E (elapsed) 
time. 

S Number of seconds of CPU time consumed by the kernel on behalf of the 
user’s process. 

U Number of seconds of CPU time devoted to the user’s process. 
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W Number of swaps. 

X Average amount of shared memory used in Kilobytes. 

The default resource-usage summary is a line of the form: 
uuu.u u sss.s s ee:ee pp % xxx +dddk iii +000 iojffpf+ww w 

where uuu.u is the user time (U), sss.s is the system time (S), ee :ee is the elapsed time 
(E), pp is the percentage of CPU time versus elapsed time (P), xxt is the average shared 
memory in Kilobytes (X), ddd is the average unshared data space in Kilobytes (D), iii 
and 000 are the number of block input and output operations respectively (I and 
the number of page faults (F), and ww is the number of swaps (W). 

verbose Set by the -v command line option, displays the words of each command after history 

substitution. 

Non-builtin command execution 

When a command to be executed is found to not be a builtin command the shell attempts to execute the 
command via execve (2). Each word in the variable path names a directory from which the shell will 
attempt to execute the command. If it is given neither a -c nor a -t option, the shell hashes the names in 
these directories into an internal table so that it will only try an exec in a directory if there is a possibility 
that the command resides there. This greatly speeds command location when a large number of directories 
are present in the search path. If this mechanism has been turned off (via unhash), or if the shell was given 
a -c or -t argument, and in any case for each directory component of path which does not begin with a 7’, 
the shell concatenates with the given command name to form a path name of a file which it then attempts to 
execute. 

Parenthesized commands are always executed in a subshell. Thus ‘(cd ; pwd) ; pwd’ prints the home direc- 
tory; leaving you where you were (printing this after the home directory), while ‘cd ; pwd’ leaves you in 
the home directory. Parenthesized commands are most often used to prevent chdir from affecting the 
current shell. 

If the file has execute permissions but is not an executable binary to the system, it is assumed to be a file 
containing shell commands and a new shell is spawned to read it 

If there is an alias for shell then the words of the alias are prepended to the argument list to form the shell 
command. The first word of the alias should be the full path name of the shell (for example, ‘$shell’). 
Note that this is a special, late occurring, case of alias substitution, and only allows words to be prepended 
to the argument list without modification. 

Argument list processing 

If argument 0 to the shell is ’ then this is a login shell. The flag arguments are interpreted as follows: 

-c Commands are read from the (single) following argument which must be present. Any remaining 
arguments are placed in argv. 

-e The shell exits if any invoked command terminates abnormally or yields a non-zero exit status. 

-f The shell will start faster, because it will neither search for nor execute commands from the file 

‘.cshrc’ in the invoker’s home directory. 

-i The shell is interactive and prompts for its top-level input, even if it appears to not be a terminal. 
Shells are interactive without this option if their inputs and outputs are terminals. 

— n Commands are parsed, but not executed. This may aid in syntactic checking of shell scripts. 

-s Command input is taken from the standard input. 

-t A single line of input is read and executed. A V may be used to escape the newline at the end of this 
line and continue onto another line. 

-v Sets the verbose variable, so that command input is echoed after history substitution. 
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-x Sets the echo variable, so that commands are echoed immediately before execution. 

-V Sets the verbose variable even before ‘.cshrc’ is executed. 

-X Is to -x as -V is to -v. 

After processing of flag arguments if arguments remain but none of the -c, -i, -s, or -t options was given 
the first argument is taken as the name of a file of commands to be executed. The shell opens this file, and 
saves its name for possible resubstitution by ‘$0’. Since many systems use either the standard version 6 or 
version 7 shells whose shell scripts are not compatible with this shell, the shell will execute such a ‘stan- 
dard’ shell if the first character of a script is not a “#’, that is, if the script does not start with a comment. 
Remaining arguments initialize the variable argv. 

Signal handling 

The shell normally ignores quit signals. Jobs running detached (either by *&’ or the bg or %... & com- 
mands) are immune to signals generated from the keyboard, including hangups. Other signals have the 
values which the shell inherited from its parent. The shell’s handling of interrupts and terminate signals in 
shell scripts can be controlled by onintr. Login shells catch the terminate signal; otherwise this signal is 
passed on to children from the state in the shell’s parent In no case are interrupts allowed when a login 
shell is reading the file ‘.logout’. 

FILES 

'/.cshrc 
'/.login 
'/.logout 
"/.history 
/bin/sh 
/tmp/sh* 

/etc/passwd 

LIMITATIONS 

Words can be no longer than 1024 characters. The system limits argument lists to 10240 characters. The 
number of arguments to a command which involves filename expansion is limited to 1/6’ th the number of 
characters allowed in an argument list. Command substitutions may substitute no more characters than are 
allowed in an argument list. To detect looping, the shell restricts the number of alias substitutions on a sin- 
gle line to 20. 

SEE ALSO 

sh(l), access(2), execve(2), fork(2), killpg(2), pipe(2), umask(2), getrlimit(2), setrlimit(2), sigvec(2), 
wait(2), tty(4), a.out(5), environ(5) Using the C-Shell in the Beginner’ s Guide to the Sun Workstation 

BUGS 

When a command is restarted from a stop, the shell prints the directory it started in if this is different from 
the current directory; this can be misleading (that is, wrong) as the job may have changed directories inter- 
nally. 

Shell builtin functions are not stoppable/restartable. Command sequences of the form ‘a ; b ; c’ are also not 
handled gracefully when stopping is attempted. If you suspend ‘b’, the shell will then immediately execute 
‘c’. This is especially noticeable if this expansion results from an alias. It suffices to place the sequence of 
commands in ()’s to force it to a subshell, that is, ‘( a ; b ; c )’. 

Control over tty output after processes are started is primitive; use the Sun Window system if you need 
better output control. 

Alias substitution is most often used to clumsily simulate shell procedures; shell procedures should be pro- 
vided rather than aliases. 

Commands within loops, prompted for by *?’, are not placed in the history list. Control structures should 
be parsed rather than being recognized as built-in commands. This would allow control commands to be 
placed anywhere, to be combined with T, and to be used with ‘&’ and *;’ metasyntax. 


Read at beginning of execution by each shell. 

Read by login shell, after ‘.cshrc’ at login. 

Read by login shell, at logout. 

Saved history for use at next login. 

Standard shell, for shell scripts not starting with a ‘#’. 
Temporary file for ‘«’. 

Source of home directories for "name’. 
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It should be possible to use the *:’ modifiers on the output of command substitutions. There are two prob- 
lems with *:’ modifier usage on *$’ substitutions: not all of the modifiers are available; only one modifier 
per variable substitution is allowed. 

Quoting conventions are contradictory and confusing. 

Symbolic links fool the shell. In particular, ‘cd ..’ doesn’t work properly once you’ve crossed through a 
symbolic link. 

set path should remove duplicate pathnames from the pathname list. These often occur because a shell 
script or a .cshrc file does something like set path=(/usr/local /usr/hosts $path) to ensure that the named 
directories are in the pathname list. 

There is no way to direct error output to one place and standard output to another place, except by invoking 
a sub-shell as follows: 

tutorial% ( command. > outfile ) >& errorfile 
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NAME 

ctags - create a tags file 
SYNOPSIS 

ctags [ -BFatuwvx ] file . . . 

DESCRIPTION 

Ctags makes a tags file for ex(l) from the specified C, Pascal and FORTRAN sources. A tags file gives the 
locations of specified objects (in this case functions and typedefs) in a group of files. Each line of the tags 
file contains the object name, the file in which it is defined, and an address specification for the object 
definition. Functions are searched with a pattern, typedefs with a line number. Specifiers are given in 
separate fields on the line, separated by blanks or tabs. Using the tags file, ex can quickly find these objects 
definitions. 

Files whose name ends in .c or .h are assumed to be C source files and are searched for C routine and 
macro definitions. Others are first examined to see if they contain any Pascal or FORTRAN routine 
definitions; if not, they are processed again looking for C definitions. 

The tag main is treated specially in C programs. The tag formed is created by prepending M to the name of 
the file, with a trailing .c removed, if any, and leading pathname components also removed. This makes 
use of ctags practical in directories with more than one program. 

OPTIONS 
—x 

-F 
-B 
-a 
-t 
-w 
-u 

FILES 

tags 

SEE ALSO 

ex(l), vi(l) 

BUGS 

Recognition of functions, subroutines and procedures for FORTRAN and Pascal is done is a very sim- 
pleminded way. No attempt is made to deal with block structure; if you have two Pascal procedures in dif- 
ferent blocks with the same name you lose. 

Does not know about #ifdefs. 


produce a list of object names, the line number and file name on which each is defined, as well as 
the text of that line and prints this on the standard output. This is a simple index which can be 
printed out as an off-line readable function index. 

use forward searching patterns (/.../) (default), 
use backward searching patterns (?...?). 
append to tags file, 
create tags for typedefs. 
suppress warning diagnostics. 

update the specified files in tags, that is, all references to them are deleted, and the new values are 
appended to the file. Beware: this option is implemented in a way which is rather slow; it is usu- 
ally faster to simply rebuild the tags file. 

output tags file 
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NAME 

date - display or set the date 
SYNOPSIS 

date [ -u ] [ yymmddhhmm [ .ss ] ] 

DESCRIPTION 

Date displays the current date and time when used without an argument. 

Only the super-user may set the date, yy is the last two digits of the year; the first mm is the month number; 
dd is the day number in the month; hh is the hour number (24 hour system); the second mm is the minute 
number; .ss (optional) specifies seconds. The year, month and day may be omitted; the current values are 
supplied as defaults. 

OPTIONS 

-u Display the date in GMT (universal time). The system operates in GMT; date normally takes care 
of the conversion to and from local standard and daylight time, -u may also be used to set GMT 
time. 

EXAMPLE 

date 10080045 

sets the date to Oct 8, 12:45 AM. 

FILES 

/usr/adm/wtmp to record time-setting 

SEE ALSO 

utmp(5) 

DIAGNOSTICS 

‘Failed to set date: Not owner’ if you try to change the date but are not the super-user. 
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NAME 

dbx - source-level debugger for C, FORTRAN 77 and Pascal programs 
SYNOPSIS 

dbx [ -r ] [ -i ] [ -I dir ] [ -k ] [ -kbd ] [ objfile [ corefile ] ] 

DESCRIPTION 

dbx is a utility for source-level debugging and execution of programs written in C, FORTRAN 77 and Pascal. 
It accepts the same commands as dbxtool( 1), using a standard terminal interface rather than the window 
system. 

Objfile is an object file produced by cc(l),/77(l) or pc{ 1) (or a combination of them) with the appropriate 
flag (— g) specified to produce symbol information in the object file. IMPORTANT: every stage of the com- 
pilation process, including the linking phase, must include the — g option. 

If no objfile is specified, use the debug command to specify the program to be debugged. The object file 
contains a symbol table which includes the names of all the source files translated by the compiler to create 
it. These files are available for perusal while using the debugger. 

If a file named core exists in the current directory or a corefile is specified, dbx can be used to examine the 
state of the program when it faulted. 

Debugger commands in the file .dbxinit are executed immediately after the symbolic information is read, if 
that file exists in the current directory, or in the user’s home directory if .dbxinit doesn’t exist in the current 
directory. 

OPTIONS 

-r Executes objfile immediately. Parameters follow the object file name (redirection is handled prop- 
erly). If the program terminates successfully, dbx exits. Otherwise, dbx reports the reason for ter- 
mination and waits for user response. Dbx reads from ! dev! tty when -r is specified and standard 
input is a file or pipe. 

-i Forces dbx to act as though standard input is a terminal or terminal emulator. 

-I dir Adds dir to the list of directories that are searched when looking for a source file. Normally dbx 
looks for source files in the current directory and in the directory where objfile is located. The 
directory search path can also be set with the use command. 

-k Kernel debugging. 

-kbd Debugs a program that sets the keyboard into up/down translation mode. This flag is necessary if 
the program you are debugging uses up/down encoding. 

USAGE 

Refer to Dbx in Program Debugging Tools for the Sun 

FILES 

a.out default object file 

core default core file 

'/.dbxinit initial commands 

SEE ALSO 

cc(l) C compiler 
f77(l) FORTRAN compiler 
pc(l) Pascal compiler 
Program Debugging Tools for the Sun 

BUGS 

Dbx does not correctly handle C variables that are local to compound statements. When printing these 
variables it often gives incorrect results. 
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Dbx does not handle FORTRAN entry points well — it treats them as if they were independent routines. 

Dbx does not handle assigning to FORTRAN complex types correctly (see the assign/set command). 

Some operations behave differently in dbx than in C. 

Dbx has two division operators — / always yields a floating-point result and div always yields an 
integral result. 

- An array or function name does not signify the address of the array or function in dbx. An array 
name signifies the entire array, and a function name signifies a call to the function with no argu- 
ments. The address of an array can be obtained by taking the address of its first element, and the 
address of a function can be obtained by taking the address of its name. 

Casts do not work with FORTRAN 77 or Pascal. 

Executable code incorporated into a source file using an #include preprocessor directive confuses dbx . 

Using both the — R and the — g compiler options when compiling programs causes dbx to access incorrect 
addresses for variables which -R stores in the text segment. 

dbx is confused by the output of program generators such as yacc and lex. 
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NAME 

dbxtool - window- and mouse-based source-level debugger for C, FORTRAN 77, and Pascal programs 
SYNOPSIS 

dbxtool [ -i ] [ -I dir ] [ -k ] [ -kbd ] [ objfile [ corefile ] ] 

DESCRIPTION 

dbxtool, a source-level debugger for C, Pascal and FORTRAN 77 programs, is a standard tool that runs 
within the SunView environment. It accepts the same commands as dbx, but provides a more convenient 
user interface. 

You can use the mouse to set breakpoints, examine the values of variables, control execution, peruse 
source files, and so on. dbxtool has separate subwindows for viewing source code, entering commands and 
other uses. 

objfile is an object file produced by cc(l),/77(l), or pc{ 1) (or a combination of them) with the appropriate 
flag (-g) specified to produce symbol information in the object file. IMPORTANT: every stage of the com- 
pilation process, including the linking phase, must include the -g option. If no objfile is specified, you can 
use the debug command to specify the program to be debugged. The object file contains a symbol table 
which includes the names of all the source files translated by the compiler to create it. These files are avail- 
able for perusal while using the debugger. 

If a file named core exists in the current directory or a corefile is specified, dbxtool can be used to examine 
the state of the program when it faulted. 

Debugger commands in the file .dbxinit are executed immediately after the symbolic information is read, if 
that file exists in the current directory, or in the user’s home directory if .dbxinit doesn’t exist in the current 
directory. 

OPTIONS 

-i Force dbxtool to act as though standard input were a terminal. 

-I dir Add dir to the list of directories that are searched when looking for a source file. Normally 
dbxtool looks for source files in the current directory and then in the directory where objfile is 
located. The directory search path can also be set with the use command. Multiple -I options 
may be given. 

-k Kernel debugging. 

-kbd Debugs a program that sets the keyboard into up/down translation mode. This flag is necessary if 
you are debugging a program that uses up/down encoding. 

USAGE 

Refer to Program Debugging Tools for the Sun 

FILES 

a.out default object file 

core default core file 

SEE ALSO 

dbx(l), 

cc(l) C compiler 
f77(l) FORTRAN compiler 
pc(l) Pascal compiler 

Programm Debugging Tools for the Sun Workstation 
The SunView Application Programmer’ s Guide 
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BUGS 

The bugs for dbx(l) apply to dbxtool as well. 

The interaction between scrolling in the source subwindow and dbx’s regular expression search commands 
is wrong. Scrolling should affect where the next search begins, but it does not. 
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NAME 

dc - desk calculator 

SYNOPSIS 

dc [ file ] 

DESCRIPTION 

Dc is an arbitrary precision arithmetic package. Ordinarily it operates on decimal integers, but one may 
specify an input base, output base, and a number of fractional digits to be maintained. The overall structure 
of dc is a stacking (reverse Polish) calculator. If an argument is given, input is taken from that file until its 
end, then from the standard input. The following constructions are recognized: 

number 

The value of the number is pushed on the stack. A number is an unbroken string of the digits 0-9. 
It may be preceded by an underscore _ to input a negative number. Numbers may contain decimal 
points. 

+ -/*%* 

The top two values on the stack are added (+), subtracted (-), multiplied (*), divided (/), remain- 
dered (%), or exponentiated Q. The two entries are popped off the stack; the result is pushed on 
the stack in their place. Any fractional part of an exponent is ignored. 

sx The top of the stack is popped and stored into a register named x, where x may be any character. If 
the s is capitalized, x is treated as a stack and the value is pushed on it. 

lx The value in register x is pushed on the stack. The register x is not altered. All registers start with 
zero value. If the 1 is capitalized, register x is treated as a stack and its top value is popped onto the 
main stack. 

d The top value on the stack is duplicated. 

p The top value on the stack is printed. The top value remains unchanged. P interprets the top of the 

stack as an ascii string, removes it, and prints it 

f All values on the stack and in registers are printed. 

q exits the program. If executing a string, the recursion level is popped by two. If q is capitalized, 
the top value on the stack is popped and the string execution level is popped by that value. 

x treats the top element of the stack as a character string and executes it as a string of dc commands. 

X replaces the number on the top of the stack with its scale factor. 

[ ... ] puts the bracketed ascii string onto the top of the stack. 

<x >x =x 

The top two elements of the stack are popped and compared. Register x is executed if they obey the 
stated relation. 

v replaces the top element on the stack by its square root. Any existing fractional part of the argu- 
ment is taken into account, but otherwise the scale factor is ignored. 

! interprets the rest of the line as a UNIX command. 

c All values on the stack are popped. 

i The top value on the stack is popped and used as the number radix for further input. I pushes the 
input base on the top of the stack. 

o The top value on the stack is popped and used as the number radix for further output. 

O pushes the output base on the top of the stack. 

k the top of the stack is popped, and that value is used as a non-negative scale factor: the appropriate 
number of places are printed on output, and maintained during multiplication, division, and 
exponentiation. The interaction of scale factor, input base, and output base will be reasonable if all 
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are changed together. 

z The stack level is pushed onto the stack. 

Z replaces the number on the top of the stack with its length. 

? A line of input is taken from the input source (usually the terminal) and executed. 

; : are used by be for array operations. 

EXAMPLE 

Print the first ten values of n! 

[lal+dsa*plalO>y]sy 

Osal 

lyx 

SEE ALSO 

bc(l), which is a preprocessor for dc providing infix notation and a C-like syntax which implements func- 
tions and reasonable control structures for programs. 

DIAGNOSTICS 

‘x is unimplemented’ where x is an octal number. 

‘stack empty’ for not enough elements on the stack to do what was asked. 

‘Out of space’ when the free list is exhausted (too many digits). 

‘Out of headers’ for too many numbers being kept around. 

‘Out of pushdown’ for too many items on the stack. 

‘Nesting Depth’ for too many levels of nested execution. 
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NAME 

dd - convert and copy a file 

SYNOPSIS 

dd [option= value] . . . 


DESCRIPTION 

dd copies a specified input file to a specified output with possible conversions. The standard input and out- 
put are used by default. The input and output block size may be specified to take advantage of raw physi- 
cal I/O. 


OPTION 
if =name 
of-name 


ibs=n 

obs=n 

bs=n 


cbs=n 


VALUES 

input file is taken from name ; standard input is default. 

output file is taken from name ; standard output is default Note that dd creates an expli- 
cit output file; therefore the seek option is usually useless with explicit output except in 
special cases such as using magnetic tape or raw disk files. 

input block size n bytes (default 512). 

output block size n bytes (default 512). 

set both input and output block size, superseding ibs and obs; also, if no conversion is 
specified, it is particularly efficient since no copy need be done 

conversion buffer size 


skip=n 

files=n 

seek=/t 


count=n 

conv=ascii 

ebcdic 

ibm 

block 

unblock 

lease 

ucase 

swab 

noerror 

sync 


skip n input records before starting copy 

copy n input files before terminating (makes sense only when input is a magtape or simi- 
lar device). 

seek n records from beginning of output file before copying. This option generally only 
works with magnetic tapes and raw disk files and is otherwise usually useless if the 
explicit output file was named with the of option. 

copy only n input records 

convert EBCDIC to ASCII 

convert ASCII to EBCDIC 

slightly different map of ASCII to EBCDIC 

convert variable length records to fixed length 

convert fixed length records to variable length 

map alphabetics to lower case 

map alphabetics to upper case 

swap every pair of bytes 

do not stop processing on an error 

pad every input record to ibs 

several comma-separated conversions 


Where sizes are specified, a number of bytes is expected. A number may end with k (kilobytes) to specify 
multiplication by 1024, b (blocks of 512 bytes) to specify multiplication by 512, or w (words) to specify 
multiplication by 4; a pair of numbers may be separated by x to indicate a product. 

Cbs is used only if ascii, unblock, ebcdic, ibm, or block conversion is specified. In the first two cases, ebs 
characters are placed into the conversion buffer, any specified character mapping is done, trailing blanks 
trimmed and new-line added before sending the line to the output. In the latter three cases, characters are 
read into the conversion buffer, and blanks added to make up an output record of size cbs. 


After completion, dd reports the number of whole and partial input and output blocks. 


EXAMPLE 
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To read an EBCDIC tape blocked ten 80-byte EBCDIC card images per record into the ASCII file*: 
tutorial% dd if=/dev/rmtO of=x ibs=800 cbs=80 conv=ascii, lease 

Note the use of raw magtape: dd is especially suited to I/O on the raw physical devices because it allows 
reading and writing in arbitrary record sizes. 

SEE ALSO 

cp(l), tr(l) 

DIAGNOSTICS 

f+p records in(out): numbers of full and partial records read( written) 

BUGS 

The ASCII/EBCDIC conversion tables are taken from the 256 character standard in the CACM Nov, 1968. 
The ibm conversion, while less blessed as a standard, corresponds better to certain IBM print train conven- 
tions. There is no universal solution. 

The block and unblock options cannot be combined with the ascii, ebcdic or ibm. Invalid combinations 
silently ignore all but the last mutually-exclusive keyword. 
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NAME 

defaultsedit - window- and mouse-based default parameters editor 

SYNOPSIS 

defaultsedit 

DESCRIPTION 

defaultsedit is a standard tool provided with the SunView environment. 

defaultsedit presents a convenient user interface for inspecting and setting default parameters. It can be 
viewed as a replacement for the traditional UNIX defaultsedit to manipulate options to the programs 
indent, mail and mailtool, stty, and defaultsedit, as well as the Menu, scrollbar, text subwindow and tty 
subwindow packages and the SunView environment. 

Any program or package which a user can customize by setting or changing a parameter could be written 
such that it gets its options from the database manipulated through defaultsedit. For information on how to 
do this see the chapter on the Defaults Database in the SunView System Programmer’ s Guide. 

OPTIONS 

defaultsedit accepts all of the generic tool arguments discussed in suntools(l). 

SUB WINDOWS 

defaultsedit consists of five subwindows. From top to bottom they are: 
buttons contains buttons labeled SAVE, QUIT, RESET, and EDIT ITEM. 

categories contains the names of all packages and programs currently in the master defaults database, 
with the current category indicated. 

message a small text subwindow where messages from defaultsedit are displayed. 

parameters shows all current default parameter names with corresponding values. 

edit a small text subwindow which enables text editing of parameter values. This is useful for 

very long text values, such as a long mailing list 

USING DEFAULTSEDIT 

SAVE Saves the current values for all categories in your private database — that is, the .defaults 

file in your home directory. 

QUIT exits without automatically saving anything. 

RESET resets the default parameters of the current category to the values in your private database. 

This is useful if you change some values, then change your mind and want to restore the ori- 
ginal values. 

EDIT ITEM Pressing the right mouse button over the EDIT ITEM button brings up a menu with three 
choices: COPY ITEM, DELETE ITEM and EDIT LABEL. Only text or numeric items can 
be edited. Also, note that edits made using this menu will appear only in your private 
defaults database, not in the master database. The three editing operations are described 
below. 

COPY ITEM Selecting COPY ITEM causes the current item to be duplicated. You can then edit both the 
label and the value of the the newly created item. Only items with text or numeric values 
can be copied in this way. COPY ITEM is useful when you want to change the number of 
instances of a certain type of item — for example, to insert a new mail alias into your 
defaults database. 

DELETE ITEM 

Selecting DELETE ITEM will delete the current item from your private database. It cannot 
be permanently deleted if the corresponding node is present in the master database. How- 
ever, you can make it behave like an undefined node by giving it the special value 
\255Undefned\255 . The first and last byte of this string have the ASCII code 255. 
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EDIT LABEL 

Selecting EDIT LABEL allows you to edit the label of the current item. When you select 
EDIT LABEL, the label of the current item changes from bold to normal face. Then you 
can select the label and edit it as a normal panel text item. 

FILES 

"/.defaults /usr/lib/defaults/*.d 
SEE ALSO 

Windows and Window-Based Tools: Beginner' s Guide 
The SuriView System Programmer’ s Guide 

BUGS 

Editing of choice items or categories is not supported by defaultsedit. Neither is editing of the master 
defaults database — to add a new program to the master defaults database, you have to edit a master 
defaults textfile. 
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NAME 

delta — make a delta (change) to an SCCS file 
SYNOPSIS 

/usr/sccs/delta [ -r SID ] [ -s ] [ -n ] [ -g list ] [ -m [ mrlist ] ] [ -y [ comment ] ] [ -p ] file . . . 
DESCRIPTION 

Delta permanently introduces into the named SCCS file changes that were made to the file retrieved by 
get( 1) (called the g-file, or generated file). 

Delta makes a delta to each named SCCS file. If a directory is named, delta behaves as though each file in 
the directory were specified as a named file, except that non-SCCS files (last component of the path name 
does not begin with s.) and unreadable files are silently ignored. If a name of - is given, the standard input 
is read (see WARNINGS ); each line of the standard input is taken to be the name of an SCCS file to be pro- 
cessed. 

Delta may issue prompts on the standard output depending upon certain options specified and flags (see 
admin (l)) that may be present in the SCCS file (see -m and -y options below). 

OPTIONS 

Options apply independendy to each named file. 

-r SID Uniquely identifies which delta is to be made to the SCCS file. The use of this option is necessary 
only if two or more outstanding get’s for editing (get -e) on the same SCCS file were done by the 
same person (login name). The SID value specified with the -r option can be either the SID 
specified on the get command line or the SID to be made as reported by the get command (see 
get{ 1)). A diagnostic results if the specified SID is ambiguous, or, if necessary and omitted on the 
command line. 

-s Do not display the created delta’s SID, number of lines inserted, deleted and unchanged in the 
SCCS file. 

-n Retain the edited g-file which is normally removed at completion of delta processing. 

-g list Specifies a list of deltas to be ignored when the file is accessed at the change level (SID) created 
by this delta. See get{ 1) for the definition of list. 

-m [mrlist] 

If the SCCS file has the v flag set (see admin(\)), a Modification Request (MR) number must be 
supplied as the reason for creating the new delta. 

If -m is not used and the standard input is a terminal, the prompt MRs? is issued on the standard 
output before the standard input is read; if the standard input is not a terminal, no prompt is issued. 
The MRs? prompt always precedes the comments? prompt (see -y option). 

MRs in a list are separated by blanks and/or tab characters. An unescaped new-line character ter- 
minates the MR list. 

Note that if the v flag has a value (see admin ( 1)), it is taken to be the name of a program (or shell 
procedure) which will validate the correctness of the MR numbers. If a non-zero exit status is 
returned from MR number validation program, delta terminates (it is assumed that the MR 
numbers were not all valid). 

-y [comment] 

Arbitrary text to describe the reason for making the delta. A null string is considered a valid com- 
ment. 

If -y is not specified and the standard input is a terminal, the prompt comments? is issued on the 
standard output before the standard input is read; if the standard input is not a terminal, no prompt 
is issued. An unescaped new-line character terminates the comment text. 

-p Display (on the standard output) the SCCS file differences before and after the delta is applied in a 
diff(l) format. 
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FILES 

All files of the form ?-file are explained in the Source Code Control System User’s Guide. The naming 
convention for these files is also described there. 

g-file Existed before the execution of delta ; removed after completion of delta . 

p-file Existed before the execution of delta ; may exist after completion of delta. 

q-file Created during the execution of delta ; removed after completion of delta . 

x-file Created during the execution of delta ; renamed to SCCS file after completion of delta. 

z-file Created during the execution of delta ; removed during the execution of delta. 

d-file Created during the execution of delta ; removed after completion of delta . 

/bin/diff Program to compute differences between the “gotten” file and the g-file . 

WARNINGS 

Lines beginning with an SOH ASCII character (binary 001) cannot be placed in the SCCS file unless the 
SOH is escaped. This character has special meaning to SCCS (see sccsfile( 5)) and will cause an error. 

A get of many SCCS files, followed by a delta of those files, should be avoided when the get generates a 
large amount of data. Instead, multiple get/delta sequences should be used. 

If the standard input (-) is specified on the delta command line, the -m (if necessary) and -y options must 
also be present. Omission of these options is an error. 

SEE ALSO 

sccs(l), admin(l), get(l), help(l), prs(l), sccsfile(5). 

Source Code Control System in Programming Tools for the Sun Workstation. 

DIAGNOSTICS 

Use help(l ) for explanations. 
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NAME 

deroff - remove nroff, troff, tbl and eqn constructs 

SYNOPSIS 

deroff [ -w ] file . . . 

DESCRIPTION 

Deroff reads each file in sequence and removes all nroff and troff command lines, backslash constructions, 
macro definitions, eqn constructs (between ‘.EQ’ and ‘.EN’ lines or between delimiters), and table descrip- 
tions and writes the remainder on the standard output. Deroff follows chains of included files (‘.so’ and 
‘.nx’ commands); if a file has already been included, a ‘.so’ is ignored and a ‘.nx’ terminates execution. If 
no input file is given, deroff reads from the standard input file. 

OPTIONS 

-w Generate a word list, one word per line. A ‘word’ is a string of letters, digits, and apostrophes, 
beginning with a letter; apostrophes are removed. All other characters are ignored. 

SEE ALSO 

troff(l), eqn(l), tbl(l) 

BUGS 

Deroff is not a complete troff interpreter, so it can be confused by subtle constructs. Most errors result in 
too much rather than too little output. 

Deroff does not work well with files that use .so to source in the standard macro package files. 
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NAME 

des - encrypt/decrypt with Data Encryption Standard 
SYNOPSIS 

des -e | -d [ -b ] [ -f ] [ -k key ] [ -s ] [ infile [ outfile ] ] 

DESCRIPTION 

des encrypts and decrypts data using the NBS Data Encryption Standard algorithm. One of -e (for encrypt) 
or -d (for decrypt) must be specified. 

The des command is provided to promote secure exchange of data in a standard fashion. 

OPTIONS 

-b Select ECB (eight bytes at a time) encryption mode. 

-f Suppress warning message when software implementation is used. 

— k key Use the encryption key specified. 

-s Selects software implementation for the encryption algorithm. 

Two standard encryption modes are supported by the des program, Cipher Block Chaining (CBC - the 
default) and Electronic Code Book (ECB - specified with -b). CBC mode treats an entire file as a unit of 
encryption, i.e., if insertions or deletions are made to the encrypted file then decryption will not succeed. 
CBC mode also ensures that regularities in clear data do not appear in the encrypted data. ECB mode 
treats each 8 bytes as units of encryptions, so if parts of the encrypted file are modified then other parts may 
still be decrypted. Identical values of clear text encrypt to identical values of cipher text 

The key used for the DES algorithm is obtained by prompting the user unless the -k key option is given. If 
the key is an argument to the des command, it is potentially visible to users executing ps(l) or a derivative. 
To minimize this possibility, des takes care to destroy the key argument immediately upon entry. 

The des command attempts to use DES hardware for its job, but will use a software implementation of the 
DES algorithm if the hardware is unavailable. Normally, a warning message is printed if the DES 
hardware is unavailable since the software is only about l/50th as fast. However, the -f option will 
suppress the warning. The -s option may be used to force use of software instead of hardware DES. 

The des command reads from standard input unless infile is specified and writes to standard output unless 
outfile is given. 

The following sections give information required to implement compatible facilities in other environments. 

Since the CBC and ECB modes of DES require units of 8 bytes to be encrypted, files being encrypted by 
the des command have 1 to 8 bytes appended to them to cause them to be a multiple of 8 bytes. The last 
byte, when decrypted, gives the number of bytes (0 to 7) which are to be saved of the last 8 bytes. The 
other bytes of those appended to the input are randomized before encryption. If, when decrypting, the last 
byte is not in the range of 0 to 7 then either the encrypted file has been corrupted or an incorrect key was 
provided for decryption and an error message is printed. 

The DES algorithm requires an 8 byte key whose low order bits are assumed to be odd-parity bits. The 
ASCII key supplied by the user is zero padded to 8 bytes and the high order bits are set to be odd-parity 
bits. The DES algorithm then ignores the low bit of each ASCII character, but that bit’s information has 
been preserved in the high bit due to the parity. 

The CBC mode of operation always uses an initial value of all zeros for the initialization vector, so the first 
8 bytes of a file are encrypted the same whether in CBC or ECB mode. 

FILES 

/dev/des? 

BUGS 

It would be better to use a real 56-bit key rather than an ASCII-based 56-bit pattern. Knowing that the key 
was derived from ASCII radically reduces the time necessary for a brute-force crytographic attack. 
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RESTRICTIONS 

This program is not available on software shipped outside the U.S. 
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NAME 

df- report free disk space on file systems 
SYNOPSIS 

df [ -i ] [ -t type ] [filesystem . . . ] [filename . . . ] 

DESCRIPTION 

df displays the amount of disk space occupied by currently mounted file systems, the amount of used and 
available space, and how much of the file system’s total capacity has been used. Used without arguments, 
df reports on all mounted file systems, producing something like: 

tutorial% df 

Filesystem kbytes used avail capacity Mounted on 

/dev/ipOa 7445 4714 1986 70% / 

/dev/ipOg 42277 35291 2758 93% /usr 

Note that used+avail is less than the amount of space in the file system (kbytes); this is because the system 
reserves a fraction of the space in the file system to allow its file system allocation routines to work well. 
The amount reserved is typically about 10%; this may be adjusted using tunefs. When all the space on a 
file system except for this reserve is in use, only the super-user can allocate new files and data blocks to 
existing files. When a file system is overallocated in this way, df may report that the file system is more 
than 100% utilized. 

If arguments to df are disk partitions (for example, IdevlipOa ) or UNIX path names, ^produces a report on 
the file system containing the named file. Thus “df .” shows the amount of space on the file system con- 
taining the current directory. 

OPTIONS 

-i Report the number of used and free inodes. 

-t type Report on filesystems of a given type (for example, nfs or 4.2). 

FILES 

/etc/mtab list of currently mounted filesystems 

SEE ALSO 

du(l), mtab(5), quot(8), tunefs(8) 
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NAME 

diff - show differences between the contents of files or directories 
SYNOPSIS 

diff [ — b ] [ -c[#] | e | f | h ] filenamel filename2 

diff [ -b ] [ -D string ] filenamel filename2 

diff [ -b ] [ — c[#] | e | f | h ] [ -1 ] [ -r ] [ -s ] [ -S name ] dirl dir2 

DESCRIPTION 

diff is a differential file comparator. When run on regular files, and when comparing text files that differ 
during directory comparison (see the notes below on comparing directories), diff tells what lines must be 
changed in the files to bring them into agreement. Except in rare circumstances, diff finds a smallest 
sufficient set of differences. If neither filenamel nor filename2 is a directory, either may be given as in 
which case the standard input is used. If filenamel is a directory, a file in that directory whose filename is 
the same as the filename of filename2 is used (and vice versa). 

There are several options for output format; the default output format contains lines of these forms: 

nl a n3,n4 
nl,n2 d n3 
nl,n2 c n3,n4 

These lines resemble ed commands to convert filenamel into filename2 . The numbers after the letters per- 
tain to filename2 . In fact, by exchanging ‘a’ for ‘d’ and reading backward one may ascertain equally how 
to convert filename2 into filenamel . As in ed, identical pairs where nl = n2 or n3 = n4 are abbreviated as a 
single number. 

Following each of these lines come all the lines that are affected in the first file flagged by ‘<’, then all the 
lines that are affected in the second file flagged by V. 

If both arguments are directories, diff sorts the contents of the directories by name, and then runs the regu- 
lar file diff program as described above on text files which are different Binary files which differ, common 
subdirectories, and files which appear in only one directory are listed. 

OPTIONS 

-b ignore trailing blanks (spaces and tabs); other strings of blanks compare equal. 

The following four options are mutually exclusive: 

-c[#] produces a diff with lines of context. The default is to present 3 lines of context and may be 
changed, (to 10, for example), by -clO. With -c the output format is modified slightly: output 
begins with identification of the files involved and their creation dates, then each change is 
separated by a line with a dozen *’s. The lines removed from filenamel are marked with 
those added to filename2 are marked V. Lines which are changed from one file to the other are 
marked in both files with *!*. 

— e produce a script of a, c and d commands for the editor ed, which will recreate filename2 from 

filenamel . 

In connection with -e, the following shell program may help maintain multiple versions of a file. 
Only an ancestral file ($1) and a chain of version-to-version ed scripts ($2,$3,...) made by diff 
need be on hand. A ‘latest version’ appears on the standard output 

(shift; cat $*; echo T,$p') | ed - $1 

Extra commands are added to the output when comparing directories with — e, so that the result is 
a sft(l) script for converting text files which are common to the two directories from their state in 
dirl to their state in dir2. 

-f produces a script similar to that of -e, not useful with ed, and in the opposite order. 

-fa does a fast, half-hearted job. It works only when changed stretches are short and well separated, 
but does work on files of unlimited length. 
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Options for the second form of diff ait as follows: 

-D string 

create a merged version of filenamel and filename! on the standard output, with C preprocessor 
controls included so that a compilation of the result without defining string is equivalent to com- 
piling filenamel, while defining string will yield filename!. 

Options when comparing directories are: 

-1 long output format; each text file diff is piped through pr to paginate it, other differences are 
remembered and summarized after all text file differences are reported. 

-r apply ^recursively to common subdirectories encountered. 

-s report files which are the same, which are otherwise not mentioned. 

-S name 

starts a directory diff in the middle, beginning with file name. 

FILES 

/tmp/d????? 

/usr/lib/diffh for -h 
/usr/bin/pr 

SEE ALSO 

crnp(l), cc(l), cotnm(l), ed(l), diff3(l), cpp(l) 

DIAGNOSTICS 

Exit status is 0 for no differences, 1 for some, 2 for trouble. 

BUGS 

Editing scripts produced under the — e or — f option are naive about creating lines consisting of a single 

When comparing directories with the -b option specified, diff first compares the files (as in cmp), and then 
runs the regular diff algorithm if they are not equal. This may cause a small amount of spurious output if 
the the only differences are in the placement of blank strings. 

The -D option ignores existing preprocessor controls in the source files, and can generate #ifdefs’s with 
overlapping scope. The output should be checked by hand, or run through cc -E and then diffed with the 
original source files. Discrpancies revealed should be corrected before compilation. 


Sun Release 3.0 


Last change: 23 September 1985 


95 



DIFF3 ( 1 ) 


USER COMMANDS 


DIFF3 ( 1 ) 


NAME 

diff3 - 3-way differential file comparison 
SYNOPSIS 

diff3 [ -ex3 ] filel file2 file3 
DESCRIPTION 

Diff3 compares three versions of a file, and publishes disagreeing ranges of text flagged with these codes: 

==== all three files differ 

====1 filel is different 

====2 file2 is different 

====3 file3 is different 

The type of change suffered in converting a given range of a given file to some other is indicated in one of 
these ways: 

f :nl a Text is to be appended after line number nl in file/, where/ = 1, 2, or 3. 

/ : nl ,n2 c Text is to be changed in the range line nl to line n2. If nl = n2, the range may be 

abbreviated to nl . 

The original contents of the range follows immediately after a c indication. When the contents of two files 
are identical, the contents of the lower-numbered file is suppressed. 

Under the -e option, dijJ3 publishes a script for the editor ed that will incorporate into filel all changes 
between file2 and file3, i.e. the changes that normally would be flagged ==== and ====3. Option -x (-3) 
produces a script to incorporate only changes flagged ==== (====3). The following command will apply 
the resulting script to ‘filel’. 

(cat script; echo 'l,$p') | ed - filel 

FILES 

/tmp/d3????? 

/usr/lib/diff3 

SEE ALSO 

diff(l) 

BUGS 

Text lines that consist of a single V will defeat -e. 
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NAME 

domainname - set or display name of current domain system 
SYNOPSIS 

domainname [ nameofdomain ] 

DESCRIPTION 

Without an argument, domainname displays the name of the current domain. Only the super-user can set 
the domainname by giving an argument; this is usually done in the startup script ietc/rc. local. Currendy, 
domains are only used by the yellow pages, to refer collectively to a group of hosts. 

SEE ALSO 

ypinit(8) 
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NAME 

du — summarize disk usage 
SYNOPSIS 

du [ -s ] [ -a ] [ name . . . ] 


DESCRIPTION 

Du gives the number of kilobytes contained in all files and, recursively, directories within each specified 
directory or file name. If name is missing, V (the current directory) is used. 

A file which has multiple links to it is only counted once. 


OPTIONS 

-s Only display the grand total. 

-a Generate an entry for each file. 

Entries are generated only for each directory in the absence of options. 

EXAMPLE 

Here is an example of using du in a directory. We used the pwd command to identify the directory, then 
used du to show the usage of all the subdirectories in that directory. The grand total for the directory is the 
last entry in the display: 

% pwd 

/usr/henry/misc 

% du 

5 ./jokes 

33 ./squash 

44 ytech.papers/lpr.document 

217 Vtech.papers/new.manager 

401 ytech.papers 

144 ./memos 

80 ./letters 

388 ./window 

93 ./messages 

15 yuseful.news 

1211 . 

% 


SEE ALSO 

df(l), quot(8) 

BUGS 

Filename arguments that are not directory names are ignored, unless you use -a . 
If there are too many distinct linked files, du counts the excess files multiply. 
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NAME 

echo - echo arguments 
SYNOPSIS 

echo [ -n ] [ argument . . . ] 

DESCRIPTION 

Echo writes its arguments on the standard output. Arguments must be separated by spaces or tabs, and ter- 
minated by a newline. 

Echo is useful for producing diagnostics in shell programs and for writing constant data on pipes. If you 
are using the Bourne Shell (sfc(l)), you can send diagnostics to the standard error file by typing: ‘echo ... 
1 >& 2 \ 

OPTIONS 

-n Don’t add the newline to the output. 
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NAME 

ed - text editor 
SYNOPSIS 

ed [ - ] [ -x ] [filename ] 

DESCRIPTION 

ed is the basic line editor in the UNIX system. Although superseded by ex and vi for most purposes, ed is 
still used by system utilities such as sees. 

You can tell ed to perform various operations on the lines you specify, (see Line Addressing , below, for a 
discussion of how to form line-addresses for ed). You can print (display) lines, change lines, insert new 
lines into the buffer, delete existing lines, you can move or copy lines to a different place in the buffer, or 
you can substitute character strings within lines. (See List of Operations, below, for a guide. Also, see 
Regular Expressions for string-matching metacharacters.) 

ed does not operate directly on the contents of a file — when editing a file, ed reads the contents of the file 
into a buffer or scratchpad. All changes made during an editing session are made on the contents of the 
buffer. The copy must be ‘saved’ or ‘written’ — using the w (write) command — to save changes. 

The command-line shown in the synopsis above invokes ed. If filename is given, ed reads a copy of 
filename into its buffer so that it can be edited (simulates an e operation on filename). 

ed commands have a simple and regular structure: commands consist of an optional line-address, or two 
optional line-addresses separated by a comma, then a single letter operation, optionally followed by some 
other parameter: 

[line-address [ , line-address ] ] operation [ parameter ] 

For example, ‘l,10p’ means ‘print (display) lines 1 through 10’ (two line-addresses), ‘5a’ means ‘append 
after line 5’ (one line-address), and d means ‘delete the current line’ (no line-address with the current line 
used as default). Parameter varies for each operation — for the move and transfer operations, for exam- 
ple, it is the line that the addressed lines are to be moved or transferred after. These operations actually 
have three line-addresses. For reading and writing a file, parameter specifies the name of the file that is to 
be read. 

ed is extremely terse in its interaction with the user — ed’s normal response to just about any problem is 
simply a question mark ?. You get this response when, for instance, ed can’t find a specified line in the 
buffer, or if a search for a regular expression fails in a substitute (s) operation. 

OPTIONS 

- Don’t display character counts normally given by the e, r, and w operations — can be used when 
the standard input is an editor script. 

-x Simulate an x operation on the named file before reading it into the buffer, to handle encryption. 
LINE ADDRESSING 

The format of ed operations above shows that an operation can be preceded by one or two line-addresses, 
both of which are optional. If only one line-address is specified, operations are performed on that specific 
line. If two line-addresses are supplied, ed operates on the inclusive range of lines between them. 

Line-addresses are usually separated from each other by a comma — for instance: 
l,10p 

prints (displays) lines 1 thru 10. 

Line addresses may also be separated by a semicolon. Whereas the starting position for line-addresses 
separated by a comma is the same place in the buffer, when a line-address is followed by a semicolon, the 
current line is set to the line-address preceding the semicolon before any subsequent line-addresses are 
interpreted. For example: 

/Domaine Chandon/ ;//p 

sets the current line to the first occurrence of the string ‘Domaine Chandon’ before starting the search for 
the second occurrence. This feature can be used to determine the starting line for forward and backward 
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searches (7\ “?’). 

Lines can be accessed (addressed, in ed terminology) in several ways, but the most easily understood way 
of addressing lines is by line number. Line numbers in ed are relative to the start of the buffer. In practice, 
addressing lines by number proves to be the most awkward to use, so ed provides other mechanisms for 
line-addressing. Note that the line numbers associated with lines in the buffer are not physically present 
with the text of the lines — they are just an addressing mechanism. 

While ed is working on the buffer, it keeps track of the line on which you last performed some operation. 
This line is called the ‘current line’. As described below, you can indicate the current line by typing a 
period character (,). 

If you don’t specify a line for an operation to operate on, most ed operations work on the line addressed by 
the current line. 

When ed starts working on a file, the current line is positioned at the last line in the buffer. Thereafter, the 
current line usually changes when any operation is performed. In general, the current line sits at the last 
line affected by whatever ed operation you used. For instance, if you print lines 1 through 10 of the buffer, 
after the lines are displayed, the current line will be positioned at line 10. 

Line-addresses are constructed from elements as shown in the list below. Some special characters are used 
as a shorthand for certain line-addresses: 

. (‘dot’) addresses the current line. 

$ addresses the last line of the buffer. 

nnn A decimal number nnn addresses the nnn-th line of the buffer. 

'x addresses the line marked with the name x, which must be a lower-case letter. Mark lines with the 
k operation described below. 

/ regular expression / 

A regular expression enclosed in slashes 7’ searches forward from the current line and stops at 
the first line containing a string that matches the regular expression. If necessary, the search 
wraps around to the beginning of the buffer. 

Iregular expression ? 

A regular expression enclosed in question marks *?’ searches backward from the current line and 
stops at the first line containing a string that matches the regular expression. If necessary the 
search wraps around to the end of the buffer. 

address±nnn 

An address followed by a plus sign V or a minus sign followed by a decimal number 
specifies that line-address plus or minus the indicated number of lines. Plus is assumed if no signs 
are given. 

±address 

An address beginning with V or ‘-’ is taken relative to the current line; in other words, ‘-5’ is 
understood to mean ‘.-5’. 

address ± 

An address ending with V or adds or subtracts 1. As a consequence of this rule and the pre- 
vious rule, the line-address ‘— ’ refers to the line before the current line. Moreover, trailing *+’ and 
‘— ’ characters have cumulative effect, so ‘ — ’ refers to the current line less 2. 

To maintain compatibility with earlier versions of ed, the character “’ in line-addresses is 
equivalent to 

ed operations do not necessarily use line-addresses; they may use one or two. Operations which don’t use 
line-addresses regard the presence of a line-address as an error. Operations which accept one or two line- 
addresses assume default line-addresses if these are not specified. If more line-addresses are given than 
such an operation requires, the last one or two (depending on what is accepted) are used. The second line- 
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address of any two-address sequence must be greater than the first line-address — that is, the second line 
must follow the first line in the buffer. 

LIST OF OPERATIONS 

ed operates in one of two major modes: command mode and text input mode, ed always starts up in com- 
mand mode. 

While you are typing commands at ed, you are in command mode. Some commands — a for append, c for 
change, and i for insert — provide for adding new text to the buffer. While ed is accepting new text, you 
are in text input mode. You exit from text input mode by typing a period V alone at the beginning of a 
line, ed then reverts to command mode. For example, here is a very short illustration of command mode 
versus text mode: 

tutorial% ed winelist ( tell ed to edit a file called winelist) 

42 {ed states there are 42 characters in the file) 

l,$p (in command mode — tell ed to print all lines) 

1978 Chateau Chunder 

1979 Redeye Canyon 

a {in command mode — tell ed to append text) 

1980 Doomsday Special {text input mode — add a new line ) 

. ( period ends text input mode) 

p ( back in command mode — print last line entered) 

1980 Doomsday Special 

w {command mode — write the file) 

65 {ed displays the number of characters written) 

q ( command mode — quit the edit session ) 

tutorial% ( back in the Shell) 

If you interrupt ed, it displays ‘?interrupted’ and returns to command mode. 

a Append Text. 

Reads the text entered in input mode and appends it to the buffer after the addressed line, a 
accepts one line-address — default line-address is the current line. The new current line is the last 
line input, or at the addressed line if no text is entered. Address ‘0’ is a valid place to append text, 
in which case text is placed at the beginning of the buffer. 

c Change Lines. 

Deletes the addressed lines, then accepts input text which replaces these lines, c accepts two 
line-addresses — default line-address is the current line. The current line is left on the last line 
input, or at the line preceding the deleted lines if no text is entered. 

d Delete Lines. 

Delete the addressed lines from the buffer, d accepts two line-addresses — default line-address is 
the current line. The line originally after the last line deleted becomes the current line; if the lines 
deleted were originally at the end, the new last line becomes the current line. 

e filename Edit a file. 

Deletes the entire contents of the buffer, and then reads in the named file, e sets the current line to 
the last line of the buffer, and reports the number of characters read into the buffer, e remembers 
filename for possible use as a default file name in a subsequent r or w operations. If no filename is 
given, the remembered filename is used, e displays a ? if the buffer has not been written out since 
the last change made — a second e operation says you really mean it 

E filename 

Same as e, but will silently allow you to quit an editing session without warning you if you have 
not written your file, e, on the other hand, reminds you to save your changes if you have altered 
the buffer at all. 

f filename Display Remembered Filename. 

Display the currently ‘remembered filename’. If filename is given, the currently ‘remembered 
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filename’ is changed to filename, 
g/regular expression! operation list 

This is the global operation: perform operation list on all lines in the range of line-addresses con- 
taining regular expression, g accepts two line-addresses — default is all lines in the buffer. Also 
see the v operation, which inverts the sense of regular expression. 

If your operation list actually takes up more than a single line, you must end every line except the 
last (the true ‘end’ of the global operation) with an escape character, ‘\\ For example, if you want 
to substitute jimjams’ for ‘frammis’, then append several lines of text to every line containing the 
string ‘widget’ and print those lines, you would type this sequence: 
g/widget/s/frammis/jimj amsA 
a\ 

new line of text\ 
another new line of text\ 

•\ 

P 

Note that the a, i, and c operations, which put ed in input mode, are permitted in the operation list ; 
the final . terminating input may be omitted if it is the last line of the operation list. The g and v 
operations are not permitted in the operation list. 

i Insert Text. 

Insert lines of text into the buffer before the addressed line, i accepts one line-address — default 
line-address is the current line. The current line is placed at the last line input; if no text is input, the 
current line is left at the line before the addressed line, i differs from a only in the placement of the 
text. 

j Join Lines. 

Joins the addressed lines into a single line; intermediate newlines simply disappear, j accepts two 
line-addresses — default is the current line and the following line. The current line is placed at the 
resulting line. 

kx Mark Line. 

Marks the addressed line with name * (the name must be a lower-case letter). The line-address form 
x then addresses this line, k accepts one line-address — default line-address is the current line. 

1 Display Non-printing Characters. 

Displays non-graphic characters in the addressed lines such that they are displayed in two-digit octal, 
and long lines are folded. 1 accepts two line-addresses — default line-address is the current line. I 
may be placed on the same line after any non-I/O operation. 

m address Move lines. 

Reposition the addressed lines after the line-addressed by address, m accepts two line-addresses to 
specify the range of lines to be moved — default line-address is the current line. The last of the 
moved lines becomes the current line. 

p Print (display) Lines. 

Displays the addressed lines, p accepts two line-addresses — default line-address is the current line. 
The current line is placed at the last line printed, p may be placed on the same line after any non-I/O 
operation. 

P Synonym for p. 
q Quit Edit Session. 

Exit from the editing session. Note, however, that the buffer is not automatically written out (do a 
‘w’ to write if you want to save your changes), ed warns you once if you haven’t saved your file — 
a second q says you really mean it. 

Q Same as q, but you don’t get any warning if you haven’t previously written out the buffer. 
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r filename Read from file. 

Reads the contents of filename into the buffer after the addressed line. If filename is not given, the 
‘remembered filename’, if any, is used (see e and f). r accepts one line-address — default line- 
address is $. If line-address ‘0’ is used, r reads the file in at the beginning of the buffer. If the read 
is successful, r displays the number of characters read in. The current line is left at the last line read 
in from the file. 

s /regular expression/replacement string / or, 
s/regular expressionlreplacement string/g 

Substitute the replacement string for the first occurrence of regular expression on each line where 
the regular expression occurs. In the first form of the s operation, only the first occurrence of the 
matched string on each line is replaced. If you use the g (global) suffix, all occurrences of the regu- 
lar expression are replaced in the line. Keep the g suffix of the s operation distinct from the g opera- 
tion itself — they are completely different, s accepts two line-addresses to delimit the range of lines 
wi thin which the substitutions should be done — default line-address is the current line. The current 
line is left at the last line substituted. 

Special Characters : 

Any punctuation character may be used instead of V to delimit the regular expression and 
the replacement string. 

An ampersand ‘&’ appearing in the replacement string is replaced by the string matching 
the regular expression. The special meaning of in this context may be suppressed by 
preceding it by ‘W 

The characters \n where n is a digit, are replaced by the text matched by the n-th regular 
subexpression enclosed between ‘\(’ and ‘\)\ When nested, parenthesized subexpressions 
are present, n is determined by counting occurrences of ‘\(’ starting from the left. Lines 
may be split by substituting new-line characters into them. The new-line in the replacement 
string must be escaped by preceding it by ‘\\ 

taddress Transfer Lines. 

Transfers a copy of the addressed lines to after line address, transfer is like move, but it makes 
copies of the lines, leaving the original text where it was. t accepts two line-addresses preceeding 
the operation letter — default line-address is default. The current line is left on the last line of the 
copy. ‘0’ is a legal line-address for the destination. 

u Undo. Undo previous substitute. 

undo undoes the effect of the the last substitute operation, providing that the current line has not 
been moved since the substitute operation . 

v/regular expression/operation list 

Like a negative of the global operation, g: perform operation list on all lines except those containing 
regular expression, v accepts two line-addresses — default is all lines in the file. 

w Write Lines. 

Write the addressed lines from the buffer into the file specified by the ‘remembered filename’, w 
accepts two line-addresses — default is all lines in the file. The current line is unchanged. If the 
write is successful, ed displays the number of characters written. 

w filename Write Lines. 

Write the addressed lines into filename. Filename is created if it does not already exist. Filename 
becomes the ‘remembered filename’ (see the e and f operations), w accepts two line-addresses — 
default is all lines in the file. The current line is unchanged. If the write is successful, ed displays 
the number of characters written. 

W filename 

Same as w, but appends the addressed lines to the named file instead of overwriting the file. W 
accepts two line-addresses — default is all lines in the file. 

x Encrypt File. 
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When x is used, ed demands a key string from the standard input. Later r, e, and w operations will 
encrypt and decrypt the text with this key by the algorithm of crypt. An explicitly empty key turns 
off encryption. 

= Display Line Number. 

Display the line number of the addressed line. = accepts one line-address — default line-address is 
$. The current line is unchanged by this operation. 

!<shell command> 

The remainder of the line after the M’ is sent to sh to be interpreted as a shell command. The current 
line is unchanged. 

address<nev/\me> 

Display the addressed line. If you type a line-address and type return, ed displays the addressed 
line. If you simply type RETURN, the line following the current line is displayed (equivalent to 
‘. +lp’). This is useful for stepping through text 

REGULAR EXPRESSIONS 

ed supports a limited form of regular expression notation. A regular expression (also known as a pattern ) 
specifies a set of strings of characters — such as ‘any string containing digits 5 through 9’ or ‘only lines 
containing uppercase letters’. A member of this set of strings is said to be matched by the regular expres- 
sion. Regular expressions or patterns are used to address lines in the buffer (see Line Addressing, above), 
and also for selecting strings to be substituted in the s (substitute) operation described previously. 

An empty regular expression, indicated by two regular expression delimiters in a row, stands for a copy of 
the last regular expression encountered. 

Any given regular expression matches the the longest among the leftmost matches in a line. 

In the following specification for regular expressions, the notation c stands for any single ordinary charac- 
ter, where a character is anything except a newline character. 

c any ordinary character except a special character matches itself. Special characters are the delim- 
iters that actually surround the regular expression, plus \ (the escape character), [ (the opening 
bracket for a character class as described below), . (period which matches any single character), 
and sometimes the * (closure) ' and $ characters. If you want a literal occurrence of one of these 
special characters you must escape them with the \ character. 

at the very start of the regular expression constrains the match to the beginning of the line. A 
match of this type is called an ‘anchored match’ because it is ‘anchored’ to a specific place in the 
line. The A character loses its special meaning if it appears in any position other than at the very 
start of the regular expression. 

$ at the very end of the regular expression constrains the match to the end of the line. A match of 
this type is called an ‘anchored match’ because it is ‘anchored’ to a specific place in the line. The 
$ character loses its special meaning if it appears in any position other than at the very end of the 
regular expression. 

. (period) matches any single character except a newline character. 

[string] A string of characters enclosed in brackets matches any one of the characters in the brackets. For 
example, [abcxyz] matches any single character from the set ‘abcxyz’. If the first character inside 
the bracket is a \ the string matches any character not inside the brackets. For instance, 
["456787] matches any character except ‘45678’. You can use a shorthand notation to refer to an 
inclusive range of characters: a-b. Such a bracketed string of characters is known as a character 
class. 

xy When two regular expressions are concatenated, they match the leftmost and then the longest pos- 
sible string that can be divided with the first part of the string matching the first regular expression, 
followed by the second string matching the second regular expression. 

* Any regular expression followed by * matches a sequence of 0 or more matches of the regular 
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expression. Such a pattern is called a closure. For example: [ a-z ] [ a-z ] * matches any string 
of one or more lower case letters. 

\( regular expression \) 

The regular expression within the \( and \) brackets essentially ‘remembers’ whatever the regular 

expression matches. This provides a mechanism for extracting parts of strings. There can be up 

to nine such partial matches in a string. Parenthesized regular expressions can be nested. 

\n where n is in the range 1 thru 9, matches a copy of the string that the bracketed regular expression 
beginning with the nth \( matched, as described in the previous paragraph on matching parts of 
strings. When nested, parenthesized subexpressions are present, n is determined by counting 
occurrences of \( starting from the left. 

Regular expressions are used in line-addresses to specify lines and in one operation (see s for substitute 
above) to specify a portion of a line which is to be replaced. If it is desired to use one of the regular 
expression metacharacters as an ordinary character, that character may be preceded by ‘V. This also 
applies to the character bounding the regular expression (often 7’) and to *V itself. 

FILES 

/tmp/e* 

ed.hup: work is saved here if telephone hangs up 

SEE ALSO 

Using the 
crypt(l) 
ex(l) 
sed(l) 
vi(l) 

BUGS 

The 1 operation mishandles del. 

The undo operation removes marks from affected lines. 

Because 0 is an illegal line-address for a w operation, it is not possible to create an empty file with ed. Use 
cat (1) to create an empty file. 

RESTRICTIONS 

Some size limitations: 512 characters per line, 256 characters per global command list, 64 characters per 
file name, and 128K characters in the temporary file. Since each line uses two bytes of memory, the limit 
on the number of lines should not be exceeded in practice. 

When reading a file, ed discards ascii nul characters and all characters after the last newline, ed refuses to 
read files containing non-ASCII characters. 

The encryption facilities of ed are not available on software shipped outside the U.S. 


ed Line Editor in Editing Text Files on the Sun Workstation. 
encode and decode 
extended line editor (part of vi) 
stream editor 
visual (display) editor 
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NAME 

eqn, neqn, checkeq - typeset mathematics 
SYNOPSIS 

eqn [ -dry ] [ -p n ] [ -sn ] [ -in ] [filename ] . . . 
neqn [ filename ] . . . 
checkeq [ filename ] . . . 

DESCRIPTION 

Eqn (and neqn ) are language processors to assist in describing equations. Eqn is a preprocessor for troff{ 1) 
and is intended for devices that can print tr off's output. Neqn is a preprocessor for nroff( 1) and is intended 
for use with terminals. Usage is almost always: 
tutorials, eqn file ... | troff 
tutorial% neqn file ... | nroff 

If no files are specified, eqn and neqn read from the standard input A line beginning with ‘.EQ’ marks the 
start of an equation; the end of an equation is marked by a line beginning with ‘.EN’. Neither of these lines 
is altered, so they may be defined in macro packages to get centering, numbering, etc. It is also possible to 
set two characters as ‘delimiters’; subsequent text between delimiters is also treated as eqn input 

Checkeq reports missing or unbalanced delimiters and .EQ/.EN pairs. 

OPTIONS 

-dxy Set equation delimiters set to characters x and y with the command-line argument. The more 
common way to do this is with ‘delim xy’ between .EQ and .EN. The left and right delimiters 
may be identical. Delimiters are turned off by ‘delim off’ appearing in the text. All text that is 
neither between delimiters nor between .EQ and .EN is passed through untouched. 

— pn Reduce subscripts and superscripts by n point sizes from the previous size. In the absence of the 

-p option, subscripts and superscripts are reduced by 3 point sizes from the previous size. 

-sn Change point size to n globally in the document. The point size can also be changed globally in 
the body of the document by using the gsize directive. 

-fn Change font to n globally in the document. The font can also be changed globally in the body of 
the document by using the gfont directive. 

EQN LANGUAGE 

Tokens within eqn are separated by spaces, tabs, newlines, braces, double quotes, tildes or circumflexes. 
Braces { } are used for grouping; generally speaking, anywhere a single character like x could appear, a 
complicated construction enclosed in braces may be used instead. Tilde (') represents a full space in the 
output, circumflex (') half as much. 

Subscripts and superscripts are produced with the keywords sub and sup. Thus x sub i makes x /( a sub i 
sup 2 produces a; 2 , and e sup {x sup 2 + y sup 2} gives «**+•>*. 

Fractions are made with over: a over b yields %■. 


sqrt makes square roots: 1 over sqrt {ax sup 2 +bx+c } results in • 


The keywords from and to introduce lower and upper limits on arbitrary things: is made with lim 

from { n-> inf } sum from 0 to nx sub i. 


Left and right brackets, braces, etc. 
over alpha right ] ~=~1 produces 

and right are braces, brackets, bai^s, c and 
right-side-only bracket). 


r of the right height are made with left and right: left [ x sup 2 +y sup 2 


X2+# 


= 1. The right clause is optional. Legal characters after left 
f for ceiling and floor, and "" for nothing at all (useful for a 


Vertical piles of things are made with pile, lpile, cpile, and rpile: pile {a above b above c) produces 
There can be an arbitrary number of elements in a pile, lpile left-justifies, pile and cpile center, with 


Sun Release 3.0 


Last change: 1 February 1985 


107 



EQN(l) 


USER COMMANDS 


EQN(l) 


different vertical spacing, and rpile right justifies. 

Matrices are made with matrix: matrix { Icol { x sub i above y sub 2 } ccol { 1 above 2} } produces y‘ 2 \. 
In addition, there is rcol for a right-justified column. 

Diacritical marks are made with dot, dotdot, hat, tilde, bar, vec, dyad, and under: x dot = f(t) bar is 
x=f (t),y dotdot bar ~= " n under is y = n, and x vec ~=~y dyad is ?=f. 

Sizes and font can be changed with size n or size ±n, roman, italic, bold, and font n. Size and fonts can 
be changed globally in a document by gsize n and gfont n, or by the command-line arguments — s n and — f h. 

Successive display arguments can be lined up. Place mark before the desired lineup point in the first equa- 
tion; place lineup at the place that is to line up vertically in subsequent equations. 

Shorthands may be defined or existing keywords redefined with define; 
define thing % replacement % 

defines a new token called thing which will be replaced by replacement whenever it appears thereafter. 
The % may be any character that does not occur in replacement. 

Keywords like sum (£), int (J), inf (°°), and shorthands like >= (>), — > (— »), and != (^) are recognized. 
Greek letters are spelled out in the desired case, as in alpha or GAMMA. Mathematical words like sin, cos, 
log are made Roman automatically, troff(l) four-character escapes like \(bu (•) can be used anywhere. 
Strings enclosed in double quotes "..." are passed through untouched; this permits keywords to be entered 
as text, and can be used to communicate with tr off when all else fails. 

SEE ALSO 

Formatting Documents on the Sun Workstation 
troff(l), tbl(l), ms(7), eqnchar(7) 

BUGS 

To embolden digits, parens, etc., it is necessary to quote them, as in ‘bold "12.3"’. 
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NAME 

error - analyze and disperse compiler error messages 
SYNOPSIS 

error [ — n ] [ — s ] [ — q ] [ — v ] [ — t suffixlist ] [ -I ignorefile ] [ name ] 

DESCRIPTION 

Error analyzes error messages produced by a number of compilers and language processors. It replaces 
the painful, traditional methods of scribbling abbreviations of errors on paper, and permits error messages 
and source code to be viewed simultaneously. 

Error looks at error messages, either from the specified file name or from the standard input, and: 

• Determines which language processor produced each error message, 

° Determines the file name and line number of the erroneous line, and, 

■ Inserts the error message into the source file immediately preceding the erroneous line. 

Error messages which can’t be categorized by language processor or content are not inserted into any file, 
but are sent to the standard output. Error touches source files only after all input has been read. 

Options are explained later on in this manual entry. 

Error is intended to be run with its standard input connected via a pipe to the error message source. Some 
language processors put error messages on their standard error file; others put their messages on the stan- 
dard output. Hence, both error sources should be piped together into error. For example, when using the 
csh syntax, 

tutorial% make -s lint | & error -q -v 

will analyze all the error messages produced by whatever programs make runs when makin g lint. 

Error knows about the error messages produced by: make, cc, cpp, ccom, as. Id, lint, pi, pc, and/77. For 
all languages except Pascal, error messages are restricted to one line. Some error messages refer to more 
than one line in more than one file, in which case error duplicates the error message and inserts it at all of 
the places referenced. 

Error does one of six things with error messages. 
synchronize 

Some language processors produce short errors describing which file they are processing. Error 
uses these to determine the file name for languages that don’t include the file name in each error 
message. These synchronization messages are consumed entirely by error. 

discard Error messages from lint that refer to one of the two lint libraries, /usrllib/llib-lc and lusr/liblllib- 
port are discarded, to prevent accidently touching these libraries. Again, these error messages are 
consumed entirely by error. 

nullify Error messages from lint can be nullified if they refer to a specific function, which is known to 
generate diagnostics which are not interesting. Nullified error messages are not inserted into the 
source file, but are written to the standard output The names of functions to ignore are taken from 
either the file named .errorrc in the user’s home directory, or from the file named by the —I 
option. If the file does not exist no error messages are nullified. If the file does exist there must 
be one function name per line. 

not file specific 

Error messages that can’t be intuited are grouped together, and written to the standard output 
before any files are touched. They are not inserted into any source file. 

file specific 

Error messages that refer to a specific file but to no specific line are written to the standard output 
when that file is touched. 

true errors 
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Error messages that can be intuited are candidates for insertion into the file to which they refer. 

Only true error messages are inserted into source files. Other error messages are consumed entirely by 
error or are written to the standard output. Error inserts the error messages into the source file on the line 
preceeding the line number in the error message. Each error message is turned into a one line comment for 
the language, and is internally flagged with the string *###’ at the beginning of the error, and “%%%’ at the 
end of the error. This makes pattern searching for errors easier with an editor, and allows the messages to 
be easily removed. In addition, each error message contains the source line number for the line the mes- 
sage refers to. A reasonably formatted source program can be recompiled with the error messages still in 
it, without having the error messages themselves cause future errors. For poorly formatted source pro- 
grams in free format languages, such as C or Pascal, it is possible to insert a comment into another com- 
ment, which can wreak havoc with a future compilation. To avoid this, format the source program so there 
are no language statements on the same line as the end of a comment. 

OPTIONS 

-n Do not touch any files; all error messages are sent to the standard output. 

-q Error asks whether the file should be touched. A ‘y’ or ‘n’ to the question is necessary to continue. 
Absence of the -q option implies that all referenced files (except those refering to discarded error 
messages) are to be touched. 

-v After all files have been touched, overlay the visual editor vi with it set up to edit all files touched, 
and positioned in the first touched file at the first error. If vi can’t be found, try ex or ed from stan- 
dard places. 

-t Take the following argument as a suffix list. Files whose suffices do not appear in the suffix list are 
not touched. The suffix list is dot seperated, and wildcards work. Thus the suffix list; 

”.c.y.f*.h" 

allows error to touch files ending with ‘.c’, ‘.y’, ‘.f*’ and ‘.y’. 

-s Print out statistics regarding the error categorization. Not too useful. 

Error catches interrupt and terminate signals, and if in the insertion phase, will orderly terminate what it is 
doing. 

FILES 

'/.errorrc 
/dev/tty 

BUGS 

Opens the teletype directly to do user querying. 

Source files with links make a new copy of the file with only one link to it. 

Changing a language processor’s format of error messages may cause error to not understand the error 
message. 

Error, since it is purely mechanical, will not filter out subsequent errors caused by ‘floodgating’ initiated 
by one syntactically trivial error. Humans are still much better at discarding these related errors. 

Pascal error messages belong after the lines affected (error puts them before). The alignment of the ‘ | ’ 
marking the point of error is also disturbed by error. 

Error was designed for work on CRT’s at reasonably high speed. It is less pleasant on slow speed termi- 
nals, and has never been used on hardcopy terminals. 


function names to ignore for lint error messages 
user’s teletype 
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NAME 

ex, edit — text editor 
SYNOPSIS 

ex[-] [-R] [ -r ] [ -t tag ] [+ command ] [-v] [-x ] [ -wnnn ] [ . .. 

edit [ options ] 

DESCRIPTION 

ex, a line editor, is the root of a family of editors that includes edit, ex, and vi (the display editor). In most 
cases vi is preferred for interactive use. 

OPTIONS 

supress all interactive feedback to the user — useful for processing ex scripts in shell files. 

-R Read only. Do not overwrite the original file. 

— r recover the indicated files after a system crash. 

-t tag edit the file containing the tag tag. A tags database must first be created using the ctags{ 1) com- 
mand. 


+ command 

start the editing session by executing command. 

-v start up in display editing state using vi(l). You can achieve the same effect by simply typing the 
vi command itself. 


-x prompt for a key to be used in encrypting the file being edited. 

-wnnn set the default window (number of lines on your terminal) to nnn — this is useful if you are dial- 
ling into the system over a slow ’phone line. 


-1 set up for editing LISP programs. 


FILES 

/usr/lib/ex?.?strings 

/usr/lib/ex?.?recover 

/usr/lib/ex?.?preserve 

/etc/termcap 

'/.exrc 

/tmp/Exnnnnn 

/tmp/Rxrtrtrtrtrt 

/usr/preserve 
SEE ALSO 


error messages 

recover command 

preserve command 

describes capabilities of terminals 

editor startup file 

editor temporary 

named buffer temporary 

preservation directory 


Editing Text Files on the Sun 

awk(l), ed(l), grep(l), sed(l), grep(l), vi(l), termcap(5), environ(5) 


BUGS 

The undo command causes all marks to be lost on lines changed and then restored if the marked lines were 
changed. 


Undo never clears the buffer modified condition. 


The z command prints a number of logical rather than physical lines. More than a screen full of output 
may result if long lines are present. 

File input/output errors don’t print a name if the command line option is used. 

There is no easy way to do a single scan ignoring case. 

The editor does not warn if text is placed in named buffers and not used before exiting the editor. 

Null characters are discarded in input files, and cannot appear in resultant files. 
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The editor checks the first five lines of the text file for commands of the form "zwcommand." or 
"vi:command ." This feature can result in unexpected behavior, and is not recommended in any case. 

RESTRICTIONS 

The encryption facilities of ex are not available on software shipped outside the U.S. 
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NAME 

expand, unexpand - expand tabs to spaces, and vice versa 
SYNOPSIS 

expand [ — tabstop ] [ —tabl,tab2,. . ,,tabn \ [filename . . . ] 
unexpand [ -a ] [filename ... ] 

DESCRIPTION 

expand copies the named files, (or the standard input) to the standard output, with tabs changed into spaces 
(blanks). Backspace characters are preserved into the output and decrement the column count for tab cal- 
culations. expand is useful for pre-processing character files (before sorting, looking at specific columns 
etc.) that contain tabs. 

Unexpand copies the named files (or the standard input) to the standard output, putting tabs back into the 
data. By default only leading spaces (blanks) and tabs are converted to strings of tabs, but this can be over- 
ridden by the —a option (see the options section below). 

EXPAND OPTIONS 
-tabstop 

Specified as a single argument sets tabs tabstop spaces apart instead of the default 8. 

—tabl.ta.b2,. . ,,tabn 

Set tabs at the columns specified by tabl. . . 

UNEXPAND OPTIONS 

—a Insert tabs when replacing a run of two or more spaces would produce a smaller output file. 
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NAME 

expr - evaluate arguments as an expression 

SYNOPSIS 

expr arg . . . 

DESCRIPTION 

Expr evaluates expressions as specified by its arguments. Each token of the expression is a separate argu- 
ment. After evaluation, the result is written on the standard output. 

The operators and keywords are listed below. The list is in order of increasing precedence, with equal pre- 
cedence operators grouped. 

expr / expr 

yields the first expr if it is neither null nor ‘O’, otherwise yields the second expr. 
expr & expr 

yields the first expr if neither expr is null or ‘O’, otherwise yields ‘O’. 
expr relop expr 

yields ‘1’ if the indicated comparison is true, ‘0’ if false. The comparison is numeric if both expr 
are integers, otherwise the comparison is lexicographic, relop is one of < (less than), <= (less than 
or equal to), = (equal to), != (not equal to), >= (greater than or equal to), and > (greater than). 

expr + expr 
expr — expr 

addition or subtraction of the arguments. 

expr * expr 
expr / expr 
expr % expr 

multiplication, division, or remainder of the arguments. 
expr : expr 

match string regular-expression 

The two forms of the matching operator above are synonymous. The matching operator compares 
the string first argument with the regular expression second argument; regular expression syntax is 
the same as that of ed( 1). The \(...\) pattern symbols can be used to select a portion of the first 
argument. Otherwise, the matching operator yields the number of characters matched (‘0’ on 
failure). 

substr string integer-1 integer-2 

extracts the subtring of string starting at position integer-1 and of length integer-2 characters. If 
integer-1 has a value greater than string, expr returns a null string. If you try to extract more 
characters than there are in string , expr returns all the remaining characters from string . Beware 
of using negative values for either integer-1 or integer-2 as expr tends to run forever in these 
cases. 

index string character-list 

reports the first position in string at which any one of the characters in character-list matches a 
character in string . 

length siring 

returns the length (that is, the number of characters) of string. 

( expr ) parentheses for grouping. 

EXAMPLES 

To add 1 to the Shell variable a: 
a='expr $a + V 
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To find the filename part (least significant part) of the pathname stored in variable a, which may or may not 
contain 7’: 

expr $a : '.*A(.*\)' T$a 
Note the quoted Shell metacharacters. 

SEE ALSO 

sh(l), test(l) 

DIAGNOSTICS 

Expr returns the following exit codes: 

0 if the expression is neither null nor ‘0’ , 

1 if the expression is null or ‘O’, 

2 for invalid expressions. 

BUGS 

Note that the match, substr, length, and index operators cannot themselves be used as ordinary strings. 
That is, the expression: 

tutorial% expr index expurgatorious length 

syntax error 

tutorial% 

generates the syntax error’ message as shown instead of the value 1 as you might expect 
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NAME 

eyacc - modified yacc allowing much improved error recovery 
SYNOPSIS 

eyacc [ -v ] [ grammar ] 

DESCRIPTION 

Eyacc is a version of yacc(l), that produces tables used by the Pascal system and its error recovery rou- 
tines. Eyacc fully enumerates test actions in its parser when an error token is in the look-ahead set This 
prevents the parser from making undesirable reductions when an error occurs before the error is detected. 
The table format is different in eyacc than it was in the old yacc, as minor changes had been made for 
efficiency reasons. 

SEE ALSO 

yacc(l) 

Practical LR Error Recovery by Susan L. Graham, Charles B. Haley and W. N. Joy; SIGPLAN Conference 
on Compiler Construction, August 1979. 

BUGS 

Pc and its error recovery routines should be made into a library of routines for the new yacc. 
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NAME 

f77 - FORTRAN 77 compiler 
SYNOPSIS 

f77 [ — c ] [ — g ] [ — a ] [ -o output ] [ -O ] [ -C ] [ -D name ] [ -D name [ =def ]] [float _option ] [ — F ] 

[ — i2 ] [- Idir ] [-m] [-N[qxscn]nnn ] [-onetrip] [ — p ] [-pg] [ -Rx] [ — S ] 

[ — u ] [ — U ] [— v ] [— w[66 ]] filename ... 

DESCRIPTION 

f77 is the UNIX FORTRAN 77 compiler, which translates programs written in the FORTRAN 77 program- 
ming language into executable load modules or into relocatable binary programs for subsequent linking 
with ld( 1). In addition to the many flag arguments (options), f77 accepts several types of files. Filenames 
ending in ./ are taken to be FORTRAN 77 source programs; they are compiled, and each object program is 
left in the file (in the current directory) whose name is that of the source with .o substituted for ./. 
Filenames ending in .F are also taken to be FORTRAN 77 source programs, but they are preprocessed by 
the C preprocessor (equivalent to a cc -E command) before they are compiled by the/77 compiler. 

Filenames ending in .r are taken to be Ratfor source programs; these are first transformed by the ratflor{ 1) 
preprocessor, then compiled by f77 . 

In the same way, filenames ending in .c or are taken to be C or assembly source programs and are com- 
piled or assembled, producing .o files. 

OPTIONS 

The following options have the same meanings as for cc(l). See ld( 1) for link-time options. 

-c Suppress linking and produce a .o file for each source file. 

-g Produce additional symbol table information for dbx{ 1). Also pass the -lg flag to ld( 1). 

-a Insert code into the program to count how many times each basic block in the program is exe- 

cuted. After the program is compiled with this option, there will be a .d file for every ./file com- 
piled with the -a option. The .d file accumulates execution data for the corresponding source file. 
The tcov( 1) utility can then be run on the source file to generate statistics about the program. 

— o output 

Name the final output file output instead of a. out. 

The following options are peculiar to /77: 

-O Optimize the object code. This invokes both the global intermediate code optimizer and the object 
code optimizer. 

— C Compile code to check that subscripts are within the declared array bounds. 

-Dname 

-Dname= definition 

Define name to the C preprocessor, as if by ‘#define’. If no definition is given, the name is 
defined as "1". ( .F suffix files only). 

float _option 

Floating-point code generation option. Can be one of: 

-fsoft software floating-point calls (This is the default). 

-fsky in-line code for Sky floating-point processor (supported only on Sun-2 systems). 

-f68881 in-line code for Motorola 68881 floating-point processor (supported only on Sun-3 

systems). 

-fswitch run-time-switched floating-point calls. The compiled object code is linked at run- 
time to routines that support one of the above types of floating-point code. This was 
the default in previous releases. Only for use with programs that are floating-point 
intensive and which must be portable to machines with various floating-point 
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options. 

When invoked without float _option, the compiler interrogates the FLOAT_OPTION environment 
variable to determine the type of floating-point code to generate. Legal values for 
FLOATOPTION are: ‘fsoft’, ‘fsky’, l f68881’, and ‘fswitch’. 

-F Apply the C preprocessor to .F files and the Ratfor preprocessor to .r files, putting the results in 
the corresponding / files, but do not compile them. No linking is done. However, any .c or .s files 
are compiled or assembled. 

-i2 Make the default size of integer and logical constants and variables two bytes rather than four 
bytes. 

-Idir ‘#include’ files whose names do not begin with 7’ are always sought by the C preprocessor first in 
the directory of the file argument, then in directories named in -I options, then in the 
Iusrlincludelf77 directory (applies to processing of .F suffix files only). 

-m Apply the M4 preprocessor to each .r file before transforming it with the Ratfor preprocessor. 

-N[qxscn]rt«« 

Make static tables in the compiler bigger. J77 complains if tables overflow and suggests you apply 
one or more of these flags. These flags have the following meanings: 
q Maximum number of equivalenced variables. Default is 150. 

x Maximum number of external names (common block, subroutine, and function names). 
Default is 200. 

s Maximum number of statement numbers. Default is 401. 

c Maximum depth of nesting for control statements (for example, DO loops). Default is 

20 . 

n Maximum number of identifiers. Default is 1009. 

One may use multiple -N options to increase the sizes of multiple tables. 

-onetrip 

Compile DO loops so that they are performed at least once if reached. FORTRAN 77 DO loops are 
not performed at all if the upper limit is smaller than the lower limit. 

-p Produce code to count the number of times each routine is called and estimate the fraction of time 
spent in each routine. The results of this profiling appear in a file called mon.out when the pro- 
gram being profiled terminates normally. An execution profile of the program can then be pro- 
duced using the prof{ 1) utility. 

-pg Produce counting code in the manner of -p, but invoke a run-time recording mechanism that 
keeps more extensive statistics and produces a gmon.out file at normal termination. An execution 
profile can then be generated by use of gprof( 1). 

-Rx Use the string x as a Ratfor option in processing ,r files. 

-S Compile the named programs, and leave the assembly language output on corresponding files 
suffixed .s (no .o file is created). 

-u Make the default type of a variable ‘undefined’ rather than using the FORTRAN default rules. 

-U Do not convert upper case letters to lower case. The default is to convert upper case letters to 
lower case, except within character string constants. 

-v Print the version number of the compiler and the name of each pass as it executes. 

-w[66] Suppress all warning messages, or if the option is -w66, supress only FORTRAN 66 compatibility 
warnings. 

Other arguments are taken to be either linker option arguments, or /77-compatible object programs, typi- 
cally produced by an earlier run, or libraries of /77-compatible routines. These programs, together with the 
results of any compilations specified, are linked (in the order given) to produce an executable program in 
the file specified by the -o option, or in a file named a. out if the -o option is not specified. 
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FILES 


file.[fFrsc] 

input file 

file.o 

object file 

a.out 

linked output 

,/fort[pid].? 

temporary 

/usr/include/f77 

directory searched by the FORTRAN 77 include statement 

/usr/lib/f77passl 

parser 

/lib/fl 

code generator 

/lib/c2 

optional optimizer 

/lib/cpp 

C preprocessor 

/lib/bin/ratfor 

Ratfor preprocessor 

/usr/lib/li bf77 . a 

Fortran library 

/lib/libc.a 

C library, see Section 3 

mon.out 

file produced for analysis by prof(l) 

gmon.out 

file produced for analysis by gprof(l) 


SEE ALSO 

FORTRAN Programmer’s Guide for the Sun Workstation 
cc(l), gprof(l), ld(l), prof(l), ratfor(l) 

DIAGNOSTICS 

The diagnostics produced by f77 itself are intended to be self-explanatory. Occasional messages may be 
produced by the linker. 
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NAME 

false, true - provide truth values 

SYNOPSIS 

true 

false 

DESCRIPTION 

True and false are usually used in a Bourne shell script. They test for the appropriate status "true" or 
"false” before running (or failing to run) a list of commands. 

EXAMPLE 

while false 
do 

command list 
done 

SEE ALSO 

csh(l), sh(l), true(l) 

DIAGNOSTICS 

False has exit status nonzero. 
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NAME 

file - determine file type 

SYNOPSIS 

file [-f ] file ... 

DESCRIPTION 

File performs a series of tests on each file in an attempt to determine what its contents are. If an argument 

appears to be ASCII, file examines the first 512 bytes and tries to guess its language. 

OPTIONS 

-f If the -f flag is used, file assumes that the filename given next on the command line is a file con- 
taining a list of files, and operates on each file listed. 

EXAMPLE 

The example illustrates the use of file on all the files in a specific user’s directory: 


% pwd 




/usr/henry/misc 




%ls 




bensusan 

fortran.mss messages 

romero 

toolkit.tr 

command.list 

jokes pascalmss 

squash 

useful.news 

counts 

letters play.msstech.papers 

v7 .stuff 

deuter 

memos roadmap.mss 

titles 

window 

% file * 




bensusan: 

roff, nroff, or eqn input text 



command.list: 

roff, nroff, or eqn input text 



counts: 

ascii text 



deuter: 

roff, nroff, or eqn input text 



fortran.mss: 

roff, nroff, or eqn input text 



jokes: 

directory 



letters: 

directory 



memos: 

directory 



messages: 

directory 



pascal.mss: 

roff, nroff, or eqn input text 



play.mss: 

roff, nroff, or eqn input text 



roadmap.mss: 

roff, nroff, or eqn input text 



romero: 

roff, nroff, or eqn input text 



squash: 

directory 



tech.papers: 

directory 



titles: 

ascii text 



toolkit.tr: 

roff, nroff, or eqn input text 



useful.news: 

directory 



v7. stuff: 

archive 




window: directory 
% 

BUGS 

file often makes mistakes. In particular, it often suggests that command files are C programs. 
Does not recognize Pascal or LISP. 


Sun Release 3.0 


Last change: 13 November 1984 


121 



FIND(l) 


USER COMMANDS 


FIND ( 1 ) 


NAME 

find - find files 
SYNOPSIS 

find pathname-list expression 
DESCRIPTION 

find, recursively descends the directory hierarchy for each pathname in the pathname-list (that is, one or 
more pathnames) seeking files that match a boolean expression written in the primaries given below. In the 
descriptions, the argument n is used as a decimal integer where +n means more than n, -n means less than 
n, and n means exactly n. 

-fstype type True if the filesystem to which the the file belongs is of type type, where type is typically 
4.2 or nfs 

-name filename True if the filename argument matches the current file name. Normal Shell argument 
syntax may be used if escaped (watch out for ‘[\ *?’ and “*’)• 

-perm onum True if the file permission flags exactly match the octal number onum (see chmod(l)). If 
onum is prefixed by a minus sign, more flag bits (017777, see chmod{ 1)) become 
significant and the flags are compared: (flags&onum)==onum . 

-prune Always returns true. Has the side effect of pruning the search tree at the file. That is, if 

the current path name is a directory, find will not descend into that directory. 

-type c True if the type of the file is c, where c is one of: 

b for block special file, 

c for character special file, 

d for directory, 

f for plain file, or 

1 for symbolic link. 

-links n True if the file has n links. 

-user uname True if the file belongs to the user unarm (login name or numeric user ID). 

-group gname True if the file belongs to group gname (group name or numeric group ID). 

-size n True if the file is n blocks long (512 bytes per block). 

-inum n True if the file has inode number n. 

-atime n True if the file has been accessed in n days. 

-mtime n True if the file has been modified in n days. 

-exec command True if the executed command returns a zero value as exit status. The end of the com- 
mand must be punctuated by an escaped semicolon. A command argument *{}’ is 
replaced by the current pathname. 

-ok command Like -exec except that the generated command is written on the standard output, then the 
standard input is read and the command executed only upon response y. 

-print Always true; the current pathname is printed. " .nr )I file"n 

-newer True if the current file has been modified more recently than the argument file. 

The primaries may be combined using the following operators (in order of decreasing precedence): 

(...) A parenthesized group of primaries and operators (parentheses are special to the Shell and must be 
escaped). 

Iprimary 

The negation of a primary (‘P is the unary not operator). 
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primary primary 

Concatenation of primaries (the and operation is implied by the juxtaposition of two primaries). 
primary -o primary 

Alternation of primaries (‘-o’ is the or operator). 

EXAMPLE 

In our local development system, we keep a file called TIMESTAMP in all the manual page directories. 
Here is how to find all entries that have been updated since TIMESTAMP was created: 
angel% find /usi7man/man2 -newer /usr/man/man2/TIMESTAMP -print 
/usr/man/man2 
/usr/man/man2/sockeL2 
/usr/man/man2/mmap.2 
angel% 

To find all the files called intro.ms starting from the current directory: 
angel% find . -name intro.ms -print 
./manuals/assembler/intro.ms 
7manuals/sun.core/intro.ms 
./manuals/driver.tut/intro.ms 
./manuals/sys.manager/uucp.impl/intro.mss 
,/supplements/general.works/unix.introduction/intro.mss 
./supplements/programming.tools/sccs/intro.mss 
angel% 

To recursively print all files names in the current directory and below, but skipping SCCS directories: 
angel% find . -name SCCS -prune -o -print 
angel% 

To recursively print all files names in the current directory and below, skipping the contents of SCCS direc- 
tories, but printing out the SCCS directory name: 

angel% find . -print -name SCCS -prune 
angel% 

To remove all files named ‘a.out’ or ‘*.o’ that have not been accessed for a week: 

angel% find / \( —name a.out — o —name ’*.o’ \) — atime +7 —exec rm ’0’ \; 
angel% 

Note that the brace ({ }) characters must be quoted when using the C-Shell. 

FILES 

/etc/passwd 

/etc/group 

SEE ALSO 

sh(l), test(l) 
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NAME 

fmt - simple text formatter 
SYNOPSIS 

fmt [ -width ] [ — c ] [filename . . . ] 

DESCRIPTION 

Fmt is a simple text formatter which reads the concatenation of input files (or standard input if none are 
given) and produces on standard output a version of its input with lines as long as possible without 
execeeding width characters. Width defaults to 72. Blank lines and interword spacing is preserved in the 
output. 

OPTIONS 

-width Fill output lines to within width columns. 

-c Crown margin mode - the first two lines following an empty line retain their indention. Subse- 
quent non-blank lines are aligned with the second. 

In normal mode, the spacing at the beginning of the input lines is preserved in the output. Lines retain their 
separation if the input indenting increases, but may be concatenated otherwise. 

Fmt is meant to format mail messages prior to sending, but may also be useful for other simple tasks. For 
instance, in the vi text editor, the command: 

!}fmt 

reformats a paragraph, making the lines reasonably even in length. 

SEE ALSO 

nroff(l), mail(l) 
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NAME 

fold - fold long lines for finite width output device 
SYNOPSIS 

fold [ -width ] [ file . • . ] 

DESCRIPTION 

Fold the contents of the specified files, or the standard input if no files are specified, breaking the lines to 
have maximum width width. The default for width is 80. Width should be a multiple of 8 if tabs are 
present, or the tabs should be expanded using expand (l) before using fold. 

SEE ALSO 

expand(l) 

BUGS 

Folding may not work correctly if underlining is present 
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NAME 

fontedit - a vfont screen-font editor 
SYNOPSIS 

fontedit [ - W [generic_tool_arg ] ] [fontjiame ] 

DESCRIPTION 

fontedit is an editor for fixed-width fonts in vfont format whose characters are no taller than 24 pixels 
(larger characters will not fit completely onto the screen). For a description of y font format, see vfont(5). 

OPTIONS 

— W generic Jool_arg 

fontedit accepts any generic tool argument as described in suntools(l). Otherwise, you can mani- 
pulate the tool via the Tool Manager Menu. 

COMMANDS 

To edit a font, type ‘fontedit’ . A. fontjiame may be supplied on the command line or may be typed into the 
option subwindow once the program has started. If it exists, the fontjiame file must be in vfont format. 
When the program starts, it displays a single large window containing four subwindows. >From top to bot- 
tom, the four subwindows are: 

1) The top subwindow, a message subwindow, displays messages, prompts, and warnings. 

2) The second subwindow from the top, an option subwindow, allows you to set global parameters for 
the entire font and specify operations for editing any single character. The options are: 

(Read) Read in the font specified in the file name field. The program will warn you if you try to 
read over a modified font. 

(Save) Write the current font onto disk with the name in file name field. 

(Exit) Quit the program; warns you if you have modified the font. 

Font name: 

The name of the font. 

Max Width and Max Height: 

The size, in pixels, of the largest character in the font. If you edit an existing font, these 
parameters are set automatically; you must set them if you are creating a new font. 
Changing either of these values for an existing font may alter the glyph of some charac- 
ters of the font. If the glyph size of a character is larger than the new max size, then that 
character is clipped to the new size (its bottom and right edges are moved in). However, if 
a glyph’s size is smaller than the new size, the glyph is left alone. 

Caps Height and X-Height: 

The distance, in pixels, between the top of a capital and lowercase letter and the baseline. 
When an existing font is edited, the values of Caps Height and X-Height are estimated 
by fontedit, and may require some adjustment. 

Baseline: The number of pixels from the top (i.e., the upper left comer) of the character to the base- 
line. For an existing font, the value of the largest baseline distance is used. For a new font, 
each character will have the same baseline distance. If this value is changed, then the 
baseline distance for all characters in the font will be the new value. 

(Apply) Apply the current values of Max Width, Max Height, Caps Height, X-Height, and 
Baseline to the font. That is, changes made to these values do not take effect until Apply 
is selected. 

Operation: 

This is a list of drawing and editing operations that you can perform on a character. For 
drawing, the left mouse button draws in black, and the middle draws in white. Operations 
are: 
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Single Pt Press a mouse button down and a grey cell will appear; move the mouse and 
the cell will follow it. Releasing the the button will draw. 

Pt Wipe Pressing a button down will draw and moving with the button down will con- 
tinue drawing until the button is released. 

Line Button down marks the end point of a line; moving with the button down 
rubber bands a line; releasing button draws the line. 

Rect Like Line except draws a rectangle. 

Cut Button down marks one end of rectangle, and moving rubber bands the out- 
line of the rectangle. Button up places the contents of the rectangle into a 
buffer and then “cuts” (draws in white) the rectangular region from the 
character. The Paste operation (below) gets the data from the buffer. 

Copy Like Cut except that the region is just copied; no change is made to the char- 
acter. 

Paste Button down displays a rectangle the size of the region in the buffer. Moving 
with the button down moves the rectangle. Button up pastes the contents of 
the buffer into the character. 

The contents of the paste buffer cannot be transferred between tools. 

In Copy or Cut mode, holding down the shift key while pressing the left or 
middle mouse button will perform a Paste action. For best results, after plac- 
ing a region in the buffer, press down the shift key and hold it down, then 
press down the mouse button. Release the mouse key to paste the region and 
then release the shift key. 

3) The third subwindow echoes the characters in the current font as they are typed. Note that the cursor 
must be in this window in order to see the characters. Your character delete key will delete the echoed 
characters. 

4) The bottom subwindow, the editing subwindow, displays eight smaller squares at its top; these are 
called edit buttons. The top section of each of these buttons contains a line of text in the form nnn: c, 
where nnn is the hexadecimal number of the character and c is the standard ASCII character 
corresponding to that number. In the lower section of the button the character of the current font, if it 
exists, is displayed. Clicking once over an editing button selects its character for editing. 

Just below this row of buttons is a box with the characters “0 9 A Z a z” in it This box is called a 
slider. The slider allows you to scroll around in the font and select which section of the font you want 
displayed in the edit buttons. The black rectangle near “a” is an indicator which shows the section of 
the font that is displayed in the buttons above. To move the indicator, select it by pressing the left or 
middle mouse button down over the indicator and then move the mouse to the left or right with the 
button down; the indicator will slide along with the cursor. Releasing the button selects the new sec- 
tion of the font. A faster method of moving about in the font is to just press down and release the 
mouse button above the area you want without bothering to drag the indicator. Another method of 
scrolling through the characters of the font is to press a key on the keyboard when the cursor is in the 
bottom window; that character is the first one displayed in die edit buttons. 

EDITING CHARACTERS: 

To edit a character, click once over the edit button where the character is displayed. When you do this, an 
edit pad will appear in the bottom subwindow. 

The edit pad consists of an editing area bordered by scales, a proof area, and 3 command buttons. The edit- 
ing area is Max Width by Max Height when the pad opens, and displays a magnified view of the selected 
character. Black squares indicate foreground pixels. The editing area is surrounded by scales which show 
the current Caps Height, X-Height and Baseline in reverse video. 
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Just outside the scales, on the top, right side, and bottom of the pad, are three small boxes with the capital 
letters "R", "B", and "A" in them. These boxes are movable sliders that change the right edge, bottom edge, 
and x-axis advance of the character respectively. In a fixed-width font, these values are usually the same 
for all characters; however, in a variable- width font these controls can be used to set these properties for 
each character. 

To the right of the pad is the proof area where the character is displayed at normal (that is, screen) resolu- 
tion and three buttons. The three buttons are: 

Undo Clicking the left or middle mouse button undoes the last operation. 

Save Stores the current representation of the character in the font. 

Quit Closes the edit pad. 

In the bottom subwindow, the right mouse button displays a menu of operations. These operations are the 
same as those in the option subwindow discussed above; you can select the current operation by either 
picking the operation in the option subwindow or by selecting the appropriate menu with the left button of 
the mouse. When the cursor is in the other subwindows, the left button displays the standard tool menu. 

FILES 

/usrlliblfontslfixedwidthfonts- Sun-supplied screen fonts 
SEE ALSO 

suntools(l), vfont (5), vswap(l) 

BUGS 

Results are unpredictable with variable-width fonts. The baseline should be greater than 0 or else the font 
cannot be read in by fontedit or by suntools. 
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NAME 

fpr - print FORTRAN file 

SYNOPSIS 

fpr 

DESCRIPTION 

fpr transforms files formatted according to FORTRAN’S carriage control conventions into files formatted 
according to UNIX line printer conventions. 

Fpr copies its input onto its output, replacing the carriage control characters with characters that will pro- 
duce the intended effects when printed using lpr( 1). The first character of each line determines the vertical 
spacing as follows: 

(blank) one line 

0 two lines 

1 to first line of next page 
+ no advance 

A blank line (that is, an empty line) is treated as if its first character is a blank. A blank that appears as a 
carriage control character is deleted. A zero is changed to a newline. A one is changed to a form feed. The 
effects of a "+" are simulated using backspaces. 

Note that fpr is known as asa in UNIX System V. 

EXAMPLES 

a.out | fpr | lpr 

fpr < f77. output | lpr 

BUGS 

Results are undefined for input lines longer than 170 characters. 
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NAME 

from - who is my mail from? 

SYNOPSIS 

from [ -s sender ] [ user ] 

DESCRIPTION 

From prints out the mail header lines in your mailbox file to show you who your mail is from. If user is 
specified, then user’s mailbox is examined instead of your own. 

OPTIONS 

-s sender 

Only display headers for mail sent by sender. 

FILES 

/usr/spool/mail/* 

SEE ALSO 

biff(l), mail(l), prmail(l) 
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NAME 

fsplit - split a multi-routine FORTRAN file into individual files 
SYNOPSIS 

fsplit [ -e efile] ... [ file ] 

DESCRIPTION 

Fsplit takes as input either a file or standard input containing FORTRAN source code. It attempts to split 
the input into separate routine files of the form name.f, where name is the name of the program unit (func- 
tion, subroutine, block data or program). The name for unnamed block data subprograms has the form 
blkdtaNNN.f where NNN is three digits and a file of this name does not already exist. For unnamed main 
programs the name has the form mainNNN.f. If there is an error in classifying a program unit, or if name.f 
already exists, the program unit will be put in a file of the form zzzNNN.f where zzzNNN.f does not already 
exist. 

Normally each subprogram unit is split into a separate file. When the -e option is used, only the specified 
subprogram units are split into separate files. E.g.: 

fsplit -e readit -e doit prog.f 

will split readit and doit into separate files. 

DIAGNOSTICS 

If names specified via the -e option are not found, a diagnostic is written to standard error. 

BUGS 

Fsplit assumes the subprogram name is on the first noncomment line of the subprogram unit Nonstandard 
source formats may confuse fsplit. 

It is hard to use -e for unnamed main programs and block data subprograms since you must predict the 
created file name. 
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NAME 

ftp - file transfer program 
SYNOPSIS 

ftp [ -v ] [-d] [ -i ] [ -n ] [ -g ] [ -t ] [ host ] 

DESCRIPTION 

ftp is the user interface to the ARPANET standard File Transfer Protocol, ftp transfers files to and from a 
remote network site. 

The client host with which ftp is to communicate may be specified on the command line. If this is done,///? 
immediately attempts to establish a connection to an FTP server on that host; otherwise,///? enters its com- 
mand interpreter and awaits instructions from the user. When ftp is awaiting commands from the user, it 
displays the prompt “ftp>”. 

OPTIONS 

Options may be specified at the command line, or to the command interpreter. 

-v show all responses from the remote server, as well as report on data transfer statistics. This is 
turned on by default if ftp is running interactively with its input coming from the user’s terminal. 

-n do not attempt “auto-login” upon initial connection. If auto-login is enabled, ftp checks the 
.netrc file in the user’s home directory for an entry describing an account on the remote machine. 
If no entry exists, ftp uses the login name on the local machine as the user identity on the remote 
machine, and prompts for a password and, optionally, an account with which to login. 

-i turn off interactive prompting during multiple file transfers. 

-g disable filename "globbing." 

-d enable debugging. 

-t enable packet tracing (unimplemented). 

COMMANDS 

! [ command ] 

Run command as a shell command on the local machine. If no command is given, invoke an 
interactive shell. 

append local-file [ remote-file ] 

Append a local file to a file on the remote machine. If remote-file is left unspecified, the local file 
name is used in naming the remote file. File transfer uses the current settings for “representation 
type”, “file structure”, and “transfer mode”. 

ascii Set the “representation type” to “network ASCII”. This is the default type. 

bell Arrange that a bell be sounded after each file transfer command is completed. 

binary Set the ‘ ‘representation type’ ’ to ‘ ‘image’ ’ . 

bye Terminate the FTP session with the remote server and exit ftp. 

cd remote-directory 

Change the working directory on the remote machine to remote-directory . 
close Terminate the FTP session with the remote server, and return to the command interpreter, 
delete remote-file 

Delete the file remote-file on the remote machine, 
debug [ debug-value ] 

Toggle debugging mode. If an optional debug-value is specified it is used to set the debugging 
level. When debugging is on, ftp prints each command sent to the remote machine, preceded by 
the string 

dir [ remote-directory ] [ local-file ] 
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Print a listing of the directory contents in the directory, remote-directory, and, optionally, placing 
the output in local-file. If no directory is specified, the current working directory on the remote 
machine is used. If no local file is specified, or local-file is — , output comes to the terminal, 
form [ format-name ] 

Set the carriage control format subtype of the “representation type” to format-name . The only 
vaMformat-name is non-print, which corresponds to the default “non-print” subtype. 

get remote-file [ local-file ] 

Retrieve the remote-file and store it on the local machine. If the local file name is not specified, it 
is given the same name it has on the remote machine. The current settings for “representation 
type”, “file structure”, and “transfer mode” are used while transferring the file. 

glob Toggle filename expansion, or "globbing", for mdelete, mget and input. If globbing is turned off, 
filenames are taken literally. 

Globbing for input is done as in csfi(l). For mdelete and mget, each remote file name is 
expanded separately on the remote machine, and the lists are not merged. 

Expansion of a directory name is likely to be radically different from expansion of the name of an 
ordinary file: the exact result depends on the remote operating system and FTP server, and can be 
previewed by doing ‘mis remote-files 

mget and mput are not meant to transfer entire directory subtrees of files. You can do this by 
transferring a tar{ 1) archive of the subtree (using a “representation type” of “image” as set by 
the binary command). 

hash Toggle hash-sign (“#”) printing for each data block transferred. The size of a data block is 1024 
bytes. 

help [ command ] 

Print an informative message about the meaning of command. If no argument is given, ftp prints a 
list of the known commands. 

led [ directory ] 

Change the working directory on the local machine. If no directory is specified, the user’s home 
directory is used. 

Is [ remote-directory ] [ local-file ] 

Print an abbreviated listing of the contents of a directory on the remote machine. If remote- 
directory is left unspecified, the current working directory is used. If no local file is specified, or if 
local-file is -, the output is sent to the terminal. 

mdelete [ remote-files ] 

Delete the remote-files on the remote machine. 

mdir remote-files local-file 

Like dir, except multiple remote files may be specified, 
mget remote-files 

Expand the remote-files on the remote machine and do a get for each file name thus produced. 
See glob for details on the filename expansion. Files are transferred into the local working direc- 
tory, which can be changed with ‘led directory’-, new local directories can be created with 
‘! mkdir directory ’ . 

mkdir directory-name 

Make a directory on the remote machine. 

mis remote-files local-file 

Like Is, except multiple remote files may be specified, 
mode [ mode-name ] 

Set the “transfer mode” to mode-name. The only valid mode-name is stream, which 
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corresponds to the default “stream” mode, 
mput local-files 

Expand wild cards in the list of local files given as arguments and do a put for each file in the 
resulting list See glob for details of filename expansion. 

open host [ port ] 

Establish a connection to the specified host FTP server. An optional port number may be sup- 
plied, in which case, ftp will attempt to contact an FTP server at that port. If the auto-login option 
is on (default), ftp will also attempt to automatically log the user in to the FTP server (see below). 

prompt Toggle interactive prompting. Interactive prompting occurs during multiple file transfers to allow 
the user to selectively retrieve or store files. By default, prompting is turned on. If prompting is 
turned off, any mget or mput will transfer all files, and any mdelete will delete all files. 

put local-file [ remote-file ] 

Store a local file on the remote machine. If remote-file is left unspecified, the local file name is 
used in naming the remote file. File transfer uses the current settings for “representation type”, 
“file structure”, and “transfer mode”. 

pwd Print the name of the current working directory on the remote machine, 
quit A synonym for bye. 
quote argl arg2 ... 

Send the arguments specified, verbatim, to the remote FTP server. A single FTP reply code is 
expected in return. 

recv remote-file [ local-file ] 

A synonym for get. 

remotehelp [ command-name ] 

Request help from the remote FTP server. If a command-name is specified it is supplied to the 
server as well. 

rename from to 

Rename the file from on the remote machine to have the name to. 

rmdir directory-name 

Delete a directory on the remote machine. 

send local-file [ remote-file ] 

A synonym for put. 

sendport 

Toggle the use of PORT commands. By default, ftp will attempt to use a PORT command when 
establishing a connection for each data transfer. If the PORT command fails, ftp will use the 
default data port When the use of PORT commands is disabled, no attempt will be made to use 
PORT commands for each data transfer. This is useful for certain FTP implementations which 
ignore PORT commands but incorrectly indicate they’ve been accepted. 

status Show the current status of ftp . 

struct [ struct-name ] 

Set the “file structure” to struct-name. The only valid struct-name is file, which corresponds to 
the default “file” structure. 

tenex Set the ‘ ‘representation type’ ’ to that needed to talk to TENEX machines, 
trace Toggle packet tracing (unimplemented), 
type [ type-name ] 

Set the “representation type” to type-name. The valid type-names are ascii for “network 
ASCII”, binary or image for “image”, and tenex for “local byte size” with a byte size of 8 
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(used to talk to TENEX machines). If no type is specified, the current type is printed. The default 
type is “network ASCII”. 

user user-name [ password ] [ account ] 

Identify yourself to the remote FTP server. If the password is not specified and the server requires 
it, ftp will prompt the user for it (after disabling local echo). If an account field is not specified, 
and the FTP server requires it, the user will be prompted for it. Unless/t/? is invoked with “auttv 
login” disabled, this process is done automatically on initial connection to the FTP server. 

verbose Toggle verbose mode. In verbose mode, all responses from the FTP server are displayed to the 
user. In addition, if verbose mode is on, when a file transfer completes, statistics regarding the 
efficiency of the transfer are reported. By default, verbose mode is on \f ftp’s commands are com- 
ing from a terminal, and off otherwise. 

? [ command ] 

A synonym for help. 

Command arguments which have embedded spaces may be quoted with quote (") marks. 

If any command argument which is not indicated as being optional is not specified, ftp will prompt for that 
argument. 

FILE NAMING CONVENTIONS 

Local files specified as arguments to ftp commands are processed according to the following rales. 

1) If the file name is specified, the standard input (for reading) or standard output (for writing) is 
used. 

2) If the first character of the file name is the remainder of the argument is interpreted as a shell 
command, ftp then forks a shell, using popen (3S) with the argument supplied, and reads (writes) 
from the standard output (standard input) of that shell. If the shell command includes spaces, the 
argument must be quoted; e.g. | Is -It"”. A particularly useful example of this mechanism is: 
“dir|more”. 

3) Failing the above checks, if “globbing” is enabled, local file names are expanded according to the 
rales used in the cj/j(1); c.f. the glob command. 

Note that remote file names are not processed, but are passed just as they are typed, except for the mdelete, 
mdir, mget, and mis commands, where they are expanded according to the rales of the remote host’s 
operating system, if any. 

FILE TRANSFER PARAMETERS 

The FTP specification specifies many parameters which may affect a file transfer. 

The “representation type” may be one of “network ASCII”, “EBCDIC”, “image”, or “local byte size” 
with a specified byte size (for PDP-lO’s and PDP-20’s mostly). The “network ASCII” and “EBCDIC” 
types have a further subtype which specifies whether vertical format control (newlines, form feeds, etc.) are 
to be passed through (“non-print”), provided in TELNET format (“TELNET format controls”), or pro- 
vided in ASA (FORTRAN) (“carriage control (ASA)”) format, ftp supports the “network ASCII” (sub- 
type non-print” only) and “image” types, plus “local byte size” with a byte size of 8 for communicat- 
ing with TENEX machines. 

The “file structure” may be one of “file” (no record structure), “record”, or “page”, ftp supports only 
the default value, which is “file”. 

The “transfer mode” may be one of “stream”, “block”, or “compressed”, ftp supports only the default 
value, which is “stream”. 

SEE ALSO 

rcp(l), ftpd(8c) 
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BUGS 

Many FTP server implementations do not support experimental operations such as print working directory. 
VAX sites running the BBN FTP server appear to ignore the PORT command while indicating complicity; 
this locks up all file transfers. 
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NAME 

gcore - get core images of running processes 
SYNOPSIS 

gcore process-id. . . . 

DESCRIPTION 

gcore creates a core image of each specified process. Such an image can be used with adb or dbx. 
For best results, stop the process before running gcore to avoid confusion from paging activity. 

FILES 

core.<process-id> core images 
SEE ALSO 

kill(l), csh(l), adb(l), dbx(l) 
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NAME 

get - get a version of an SCCS file 
SYNOPSIS 

/usr/sccs/get [ -r SID ] [ -c cutoff] [ -i list ] [ -x list ] [ -a seq-no. ] [ -k ] [ -e ] [ -1 [ p ] ] 

[ -p ] [ -m ] [ -n ] [ -s ] [ -b ] [ -g ] [ -t ] filename . . . 

DESCRIPTION 

get generates an ASCII text file from each named SCCS file according to the specified option. Arguments 
may be specified in any order, options apply to all named SCCS files. If a directory is named, get behaves 
as though each file in the directory were specified as a named file, except that non-SCCS files (last com- 
ponent of the path name does not begin with s.) and unreadable files are silently ignored. If a name of - is 
given, the standard input is read; each line of the standard input is taken to be the name of an SCCS file to 
be processed. Again, non-SCCS files and unreadable files are silendy ignored. 

The generated text is normally written into a file called the g-file whose name is derived from the SCCS file 
name by simply removing the leading s.; (see also FILES, below). 

OPTIONS 

Opdons are explained below as though only one SCCS file is to be processed, but the effects of any opdon 
argument applies independently to each named file. 

-r SID The 5 CCS TDentification string (SID) of the version (delta) of an SCCS file to be retrieved. Table 
1 below shows, for the most useful cases, what version of an SCCS file is retrieved (as well as the 
SID of the version to be eventually created by delta if the -e option is also used), as a function of 
the SID specified. 

-c cutoff 

Cutoff date-time, in the form; YY[ MM[ DD[ HH[ MM[ SS ] ] ] ] ] 

No changes (deltas) to the SCCS file which were created after the specified cutoff date-time are 
included in the generated ASCII text file. Units omitted from the date-time default to their max- 
imum possible values; that is, — c7502 is equivalent to — c750228235959. Any number of non- 
numeric characters may separate the various 2 digit pieces of the cutoff date-time. This feature 
allows one to specify a cutoff date in the form: -ell 1212 9:22:25. Note that this implies that one 
may use the %E% and %U% identification keywords. 

-e This get is for editing or making a change (delta) to the SCCS file via a subsequent use of delta . A 
/usr/sccs/get — e applied to a particular version (SID) of the SCCS file prevents further 
/usr/sccs/get -e commands on the same SID until delta is run or the j (joint edit) flag is set in the 
SCCS file (see admin{ 1)). Concurrent use of /usr/sccs/get -e for different SIDs is always 
allowed. 

If the g-file generated by a /usr/sccs/get -e is accidentally ruined in the process of editing it, it 
may be regenerated by re-running a get with the — k option in place of the — e option. 

SCCS file protection specified via the ceiling, floor, and authorized user list stored in the SCCS file 
(see adminll)) are enforced when the -e option is used. 

-b Used with the -e option to indicate that the new delta should have an SID in a new branch as 
shown in Table 1. This option is ignored if the b flag is not present in the file (see admin{ 1)) or if 
the retrieved delta is not a leaf delta. (A leaf delta is one that has no successors on the SCCS file 
tree.) 

Note: A branch delta may always be created from a non-leaf delta. 

-Hist A list of deltas to be included (forced to be applied) in the creation of the generated file. The list 
has the following syntax: 

<list> ::= <range> | <list> , <range> 

<range> ::= SID | SID - SID 

SID, the SCCS Identification of a delta, may be in any form shown in the ‘SID Specified’ column of 
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Table 1. Partial SIDs are interpreted as shown in the ‘SID Retrieved’ column of Table 1. 

-x list A to of deltas to be excluded (forced not to be applied) in the creation of the generated file. See 
the — i option for the list format. 

-k Suppress replacement of identification keywords (see below) in the retrieved text by their value 
The -k option is implied by the -e option. 

-1 [ p ] Write a delta summary into an l-file . If -Ip is used, the delta summary is written on the standard 
output and the l-file is not created. See FILES for the format of the l-file. 

-P Write the text retrieved from the SCCS file to the standard output No g-file is created. All output 
which normally goes to the standard output goes to the standard error file instead, unless the -s 
option is used, in which case it disappears. 

-s Suppress all output normally written on the standard output. However, fatal error messages 
(which always go to the standard error file) remain unaffected. 

-m Precede each text line retrieved from the SCCS file with the SID of the delta that inserted the text 
line in the SCCS file. The format is: SID, followed by a horizontal tab, followed by the text line. 

— n Precede each generated text line with the %M% identification keyword value (see below). The 

format is: %M% value, followed by a horizontal tab, followed by the text line. When both the -m 
and -n options are used, the format is: %M% value, followed by a horizontal tab, followed by the 
-m option generated format. 

-g Do not actually retrieve text from the SCCS file. It is primarily used to generate an l-file , or to ver- 
ify the existence of a particular SID. 

-t Access the most recently created (‘top’) delta in a given release (for example, -rl), or release and 
level (for example, -rl.2). 


—a seq-no. 

The delta sequence number of the SCCS file delta (version) to be retrieved (see sccsfile (5)). This 
option is used by the comb command; it is not a generally useful option, and users should not use 
it If both the -r and -a options are specified, the -a option is used. Care should be taken when 
using the -a option in conjunction with the -e option, as the SID of the delta to be created may not 
be what one expects. The — r option can be used with the —a and — e options to control the naming 
of the SID of the delta to be created. 

For each file processed, get responds (on the standard output) with the SID being accessed and with the 
number of lines retrieved from the SCCS file. 

If the -e option is used, the SID of the delta to be made appears after the SID accessed and before the 
number of lines generated. If there is more than one named file or if a directory or standard input is named, 
each file name is printed (preceded by a new-line) before it is processed. If the -i option is used included 
deltas are listed following the notation ‘Included’; if the — x option is used, excluded deltas are listed fol- 
lowing the notation ‘Excluded’. 
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TABLE 1. Determination of SCCS Identification String 


SID* 

-b Option 

Other 

SID 

SID of Delta 

Specified 

Usedt 

Conditions 

Retrieved 

to be Created 

none! 

no 

R defaults to mR 

mR.mL 

mR.(mL+l) 

none$ 

yes 

R defaults to mR 

mR.mL 

mR.mL.(mB+l).l 

R 

no 

R > mR 

mR.mL 

R.l*** 

R 

no 

R = mR 

mR.mL 

mR.(mL+l) 

R 

yes 

R > mR 

mR.mL 

mR.mL.(mB+l).l 

R 

yes 

R = mR 

mR.mL 

mR.mL.(mB+l).l 

R 

- 

R < mR and 

R does not exist 

hR.mL** 

hR.mL.(mB+l).l 

R 

— 

Trunk succ.# 
in release > R 
and R exists 

R.mL 

R.mL.(mB+l).l 

R.L 

no 

No trunk succ. 

R.L 

R.(L+1) 

R.L 

yes 

No trunk succ. 

R.L 

R.L.(mB+l).l 

R.L 

- 

Trunk succ. 
in release > R 

R.L 

R.L.(mB+l).l 

R.L.B 

no 

No branch succ. 

RU.B.mS 

R.L.B.(mS+l) 

R.L.B 

yes 

No branch succ. 

R.L.B.mS 

R.L.(mB+l).l 

R.L.B.S 

no 

No branch succ. 

R.L.B.S 

R.L.B.(S+1) 

R.L.B.S 

yes 

No branch succ. 

R.L.B.S 

R.L.(mB+l).l 

R.L.B.S 

- 

Branch succ. 

R.L.B.S 

R.L.(mB+l).l 

* ‘R’ 

‘L’, ‘B’, 

and ‘S’ are the ‘release’, ‘level’, 

‘branch’, and ‘sequence’ components of the SID, 


respectively; ‘m’ means ‘maximum’. Thus, for example, ‘R.mL’ means ‘the maximum level 
number within release R’; ‘R.L.(mB+l).l’ means ‘the first sequence number on the new branch 
(that is, maximum branch number plus one) of level L within release R’. Note that if the SID 
specified is of the form ‘R.L’, ‘R.L.B’, or ‘R.L.B.S’, each of the specified components must exist 

** ‘hR’ is the highest existing release that is lower than the specified, nonexistent, release R. 

*** Forces creation of the first delta in a new release. 

# Successor. 

f The — b option is effective only if the b flag (see admin (l)) is present in the file. An entry of — 

means ‘irrelevant’. 

$ This case applies if the d (default SID) flag is not present in the file. If the d flag is present in the 
file, the SID obtained from the d flag is interpreted as if it had been specified on the command line. 
Thus, one of the other cases in this table applies. 

IDENTIFICATION KEYWORDS 

Identifying information is inserted into the text retrieved from the SCCS file by replacing identification key- 
words with their value wherever they occur. The following keywords may be used in the text stored in an 

SCCS file: 

Keyword Value 

%M% Module name: either the value of the m flag in the file (see admin( 1)), or if absent, the name of 
the SCCS file with the leading s. removed. 

%l% SCCS identification (SID) (%R%.%L%.%B%.%S%) of the retrieved text. 

%R% Release. 

%L% Level. 
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%B% Branch. 

%S% Sequence. 

% D % Current date ( YY/MM/DD). 

%H% Current date (MM/DD/YY). 

%T% Current time (HH:MM:SS). 

%E% Date newest applied delta was created (YY/MM/DD). 

%G% Date newest applied delta was created (MM/DD/YY). 

% U% Time newest applied delta was created (HH:MM:SS). 

% Y % Module type: value of the t flag in the SCCS file (see admin(l)). 

% F % SCCS file name. 

%P% Fully qualified SCCS file name. 

%Q% The value of the q flag in the file (see admin (1)). 

%C% Current line number. This keyword is intended for identifying messages output by the program 
such as ‘this shouldn’t have happened’ type errors. It is not intended to be used on every line to 
provide sequence numbers. 

% Z % The 4-character string @(#) recognizable by what. 

%W% A shorthand notation for constructing what strings for UNIX program files. %W% = 
%Z%%M%<horizontal-tab>%I% 

%A% Another shorthand notation for constructing what strings for non-UNIX program files %A% = 
%Z%%Y% %M% %1%%Z% 

FILES 

Several auxiliary files may be created by get, These files are known generically as the g-file, l-file, p-file, 
and z-file. The letter before the hyphen is called the tag. An auxiliary file name is formed from the SCCS 
file name, the last component of all SCCS file names must be of the form sjnodule-name, the auxiliary files 
are named by replacing the leading s with the tag. The g-file is an exception to this scheme: the g-file is 
named by removing the s. prefix. For example, s.xyz.c, the auxiliary file names would be xyz.c, ljcyz.c, 
p.xyz.c, and z.xyz.c, respectively. 

The g-file, which contains the generated text, is created in the current directory (unless the -p option is 
used). A g-file is created in all cases, whether or not any lines of text were generated by the get. It is 
owned by the real user. If the -k option is used or implied its mode is 644; otherwise its mode is 444. 
Only the real user need have write permission in the current directory. 

The l-file contains a table showing which deltas were applied in generating the retrieved text The l-file is 
created in the current directory if the -1 option is used; its mode is 444 and it is owned by the real user. 
Only the real user need have write permission in the current directory. 

Lines in the l-file have the following format: 

a. A blank character if the delta was applied; 

* otherwise. 

b. A blank character if the delta was applied or wasn’t applied and ignored; 

* if the delta wasn’t applied and wasn’t ignored. 

c. A code indicating a ‘special’ reason why the delta was or was not applied: 

‘I’: Included. 

‘X’: Excluded. 

‘C’: Cut off (by a -c option). 

d. Blank. 

e. SCCS identification (SID). 

f. Tab character. 

g. Date and time (in the form YY/MM/DD HH:MM:SS) of creation. 

h. Blank. 

i. Login name of person who created delta. 

The comments and MR data follow on subsequent lines, indented one horizontal tab character. A 
blank line terminates each entry. 
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The p-file passes information resulting from a /usr/sccs/get -e along to delta. Its contents are also used to 
prevent a subsequent execution of a /usr/sccs/get -e for the same SID until delta is executed or the joint 
edit flag, j, (see admin( 1)) is set in the SCCS file. The p-file is created in the directory containing the SCCS 
file and the effective user must have write permission in that directory. Its mode is 644 and it is owned by 
the effective user. The format of the p-file is: the gotten SID, followed by a blank, followed by the SID that 
the new delta will have when it is made, followed by a blank, followed by the login name of the real user, 
followed by a blank, followed by the date-time the get was executed, followed by a blank and the — i option 
if it was present, followed by a blank and the — x option if it was present, followed by a new-line. There 
can be an arbitrary number of lines in the p-file at any time; no two lines can have the same new delta SID. 

The 2 -file serves as a lock-out mechanism against simultaneous updates. Its contents are the binary (2 
bytes) process ID of the command (that is, get) that created it. The z-file is created in the directory contain- 
ing the SCCS file for the duration of get. The same protection restrictions as those for the p-file apply for 
the z-file. The z-file is created mode 444. 

SEE ALSO 

sccs(l), admin(l), delta(l), help(l), prs(l), what(l), sccsfile(5) 

Source Code Control System in Programming Tools for the Sun Workstation. 

DIAGNOSTICS 

Use help for explanations. 

BUGS 

If the effective user has write permission (either explicitly or implicitly) in the directory containing the 
SCCS files, but the real user doesn’t, only one file may be named when the -e option is used. 
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NAME 

get_selection - copy the contents of a SunView selection to standard out 
SYNOPSIS 

get_selection [1 1 2 1 3 ] 

DESCRIPTION 

get ^selection prints the contents of the indicated selection on standard out A selection is a collection of 
objects (e.g. characters) picked with the mouse in the SunView window system. 

OPTIONS 

The optional argument indicates which selection is to be printed: -1 is primary, -2 is secondary -3 is 
shelf. The default is primary. 

EXAMPLE 

The following line in a SunView root menu file provides a menu command to print the primary selection 
on the user’s default printer: 

"Print It" csh -c "get_selection 1 1 lpr" 

(Specify your SunView root menu as the value of the Rootmenu Jilename parameter in defaultsedit(l)). 
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NAME 

gfxtool - Run graphics programs in the SunWindows environment 
SYNOPSIS 

gfxtool [ -C ] [ program [ arguments ] ] 

OPTIONS 

-C Redirect system console output to this instance of gfxtool. 

gfxtool also accepts all of the generic tool arguments; see suntools(l) for a list of these arguments. 

If a program argument is present, gfxtool runs it. If there are no arguments, gfxtool runs the program 
corresponding to your shell environment variable. If this environment variable is not available, then 
gfxtool runs /bin/sh. 


DESCRIPTION 

gfxtool is a standard tool provided with SunWindows. It allows you to run graphics programs that don’t 
overwrite the terminal emulator from which they run. 

gfxtool has two subwindows: a terminal subwindow and an empty subwindow. The terminal subwindow 
contains a running shell, just like the shelltool (see shelltool(l)). Programs invoked in the terminal subwin- 
dow can run in the empty sub window. You can move the boundary between these two subwindows as 
described in suntools(l) under The Tool Manager. If you wish, you can make gfxtool your console by 
entering a first argument of -C. 

Normally you can use the mouse and keyboard anywhere in the empty subwindow to access Tool Manager 
functions. However, some graphics programs which run in this window may take over inputs directed to it. 
For example, SunCore uses the mouse and keyboard for its own input. When you run such tools, access 
the Tool Manager menu from the tool boundaries or namestripe. 

Most of the graphics demo programs in /usr/demo will run in gfxtool. In particular, the following demos 
run in gfxtool: 

/usr/demo/bouncedemo 

Displays a bouncing square. Place a -n followed by a decimal number on the command line to 
indicate how many repetitions of the bounce sequence should be done. 

/usr/demo/spheresdemo 

Laboriously computes a random collection of shaded spheres. Place a -n followed by a decimal 
number on the command line to indicate how many spheres should be drawn. Colored spheres are 
drawn on color displays. 

/usr/demo/jumpdemo 

Simulates the famous Star Wars jump to light-speed sequence using vector drawing. Place a -n 
followed by a decimal number up to 500 to indicate how many stars should be used in the star 
field. Colored stars are drawn on color displays. A -c on the command line directs the program to 
rotate the color map, thus producing a sparkling effect 

/usr/demo/framedemo 

Displays a series of frames, each of which contains a 256 by 256 image formed of pixels one deep 
(that is, the image is a square monochrome bitmap, with 256 bits on a side). The frames must be 
in the files framed through frame. n on the current working directory, and are displayed in numeri- 
cal order. A set of sample frames is available to you in the directory lusrldemol globeframes/* . 
Put a -n followed by a decimal number on the command line to indicate how many times to cycle 
through the frames. If you move the cursor into the image window, you can type certain charac- 
ters to affects the rate at which the frames are displayed. The initial rate is one frame per second. 
Typing “S” causes an additional one second delay between frames. Typing “F” removes one 
second from the inter-frame delay. Typing “s” adds l/20th of a second. Typing “f ’ removes 
l/20th of a second. Typing “Ff” makes the delay as small as possible. 
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For all these demos the following is true: if no -n flag appears on the command line then the program runs 
continuously until you interrupt it. A -r flag on the command line turns the window into a retained win- 
dow. This allows the image to reappear when uncovered instead of restarting the demo. You can also 
invoke all these demos from the workstation console, i.e., outside of the suntools window environment. A 
-d flag followed by a display device name as in "bouncedemo -d /dev/cgoneO” directs the demo to run on 
a display other than the console. 

SEE ALSO 

suntools (1) 
shelltool{ 1) 

FILES 

'/.ttyswrc 

/usr/bin/gfxtool 

/usr/bin/suntools 

/usr/demo/* 

/usr/src/sun/suntool/gfxtool.c 

BUGS 

If more than 256 characters are input to a terminal emulator subwindow without an intervening newline, 
the terminal emulator may hang. If this occurs, display the Tool Manager Menu; the "TTY Hung?" sub- 
menu there has one item, "Flush input", that you can invoke to correct the problem. 
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NAME 

gprof — display call-graph profile data 
SYNOPSIS 

gprof [ -a ] [ -b ] [ -c ] [ -e name ] [ -E name ] [ -f name ] [ -F name ] [ — s ] [ — z ] 

[ object-file [ profile-file . . . ] ] 

DESCRIPTION 

Gprof produces an execution profile of C, Pascal, or FORTRAN 77 programs. The effect of called routines 
is incorporated in the profile of each caller. The profile data is taken from the call-graph profile file 
(gmon.out default) which is created by programs compiled with the -pg option of cc, pc, and/77. That 
option also links in versions of the library routines which are compiled for profiling. The symbol table in 
the named object file (a.out default) is read and correlated with the call-graph profile file. If more than one 
profile file is specified, the gprof output shows the sum of the profile information in the given profile files. 

First, a flat profile is given, similar to that provided by prof( 1). This listing gives the total execution times 
and call counts for each of the functions in the program, sorted by decreasing time. 

Next, these times are propagated along the edges of the call-graph. Cycles are discovered, and calls into a 
cycle are made to share the time of the cycle. A second listing shows the functions sorted according to the 
time they represent, including the time of their call graph descendants. Below each function entry is shown 
its (direct) call-graph children, and how their times are propagated to this function. A similar display 
above the function shows how this function’s time and the time of its descendants is propagated to its 
(direct) call-graph parents. 

Cycles are also shown, with an entry for the cycle as a whole and a listing of the members of the cycle and 
their contributions to the time and call counts of the cycle. 

Beware of quantization errors. The granularity of the sampling is shown, but remains statistical at best. It 
is assumed that the time for each execution of a function can be expressed by the total time for the function 
divided by the number of times the function is called. Thus the time propagated along the call-graph arcs 
to parents of that function is directly proportional to the number of times that arc is traversed. 

The profiled program must call exit (2) or return normally for the profiling information to be saved in the 
gmon.out file. 

OPTIONS 

-a suppress printing statically declared functions. If this option is given, all relevant information 
about the static function (for instance, time samples, calls to other functions, calls from other func- 
tions) belongs to the function loaded just before the static function in the a. out file. 

-b display a description of each field in the profile. 

-c the static call-graph of the program is discovered by a heuristic which examines the text space of 

the object file. Static-only parents or children are indicated with call counts of 0. 

-e name 

suppress printing the graph profile entry for routine name and all its descendants (unless they have 
other ancestors that aren’t suppressed). More than one — e option may be given. Only one name 
may be given with each -e option. 

-E name 

suppress printing the graph profile entry for routine name (and its descendants) as -e, above, and 
also exclude the time spent in name (and its descendants) from the total and percentage time com- 
putations. More than one -E option may be given. For example, -E mcount -E mcleanup is the 
default. 

-f name 

print the graph profile entry only for routine name and its descendants. More than one — f option 
may be given. Only one name may be given with each — f option. 
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— F name 

print the graph profile entry only for routine name and its descendants (as -f, above) and also use 
only the times of the printed routines in total time and percentage computations. More than one 
-F option may be given. Only one name may be given with each -F option. The -F option over- 
rides the -E option. 

produce a profile file gmon.sum which represents the sum of the profile information in all the 
specified profile files. This summary profile file may be given to subsequent executions of gprcf 
(probably also with a -s) option to accumulate profile data across several runs of an a. out file. 

display routines which have zero usage (as indicated by call counts and accumulated time). This 
is useful in conjunction with the -c option for discovering which routines were never called. 

the namelist and text space 
gmon.out dynamic call-graph and profile 

gmon.sum summarized dynamic call-graph and profile 

SEE ALSO 

monitor(3), profil(2), cc(l), prof(l) 

Graham, S.L., Kessler, P.B., McKusick, M.K., ‘gprof: A Call Graph Execution Profiler’, Proceedings of 
the SIGPLAN ’82 Symposium on Compiler Construction, SIGPLAN Notices, Vol. 17, No 6 pp 120-126 
June 1982. ’ 

BUGS 

Parents which are not themselves profiled will have the time of their profiled children propagated to them, 
but they will appear to be spontaneously invoked in the call-graph listing, and will not have their time pro- 
pagated further. Similarly, signal catchers, even though profiled, will appear to be spontaneous (although 
for more obscure reasons). Any profiled children of signal catchers should have their times propagated 
properly, unless the signal catcher was invoked during the execution of the profiling routine, in which case 
all is lost 


-s 


-z 

FILES 

a.out 
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NAME 

graph - draw a graph 
SYNOPSIS 

graph [ -a spacing [ start ] ] [ -b ] [ -c string ] [ -g gridstyle ] [ -I label ] 

[ -m connectmode ] [ -s ] [ -x [ 1 ] lower [ upper [ spacing ] ] ] 

[ -y [ 1 ] lower [ upper [ spacing ] ] ] [ -h fraction ] [ -w fraction ] [ -r fraction ] 

[ -u fraction ] [ -t ] . . . 

DESCRIPTION 

Graph with no options takes pairs of numbers from the standard input as abscissas and ordinates of a 
graph. Successive points are connected by straight lines. The graph is encoded on the standard output for 
display by the plot( 1G) filters. 

If the coordinates of a point are followed by a nonnumeric string, that string is printed as a label beginning 
on the point. Labels may be surrounded with quotes in which case they may be empty or contain 
blanks and numbers; labels never contain newlines. 

A legend indicating grid range is produced with a grid unless the -s option is present. 

OPTIONS 

Each option is recognized as a separate argument. 

-a spacing [ start ] 

Supply abscissas automatically (they are missing from the input); spacing is the spacing (default 
1). start is the starting point for automatic abscissas (default 0 or lower limit given by -x). 

-b Break (disconnect) the graph after each label in the input 

— c string 

String is the default label for each point. 

— g gridstyle 

Gridstyle is the grid style: 0 no grid, 1 frame with ticks, 2 full grid (default). 

-1 label is label for graph. 

-m connectmode 

is mode (style) of connecting lines: 0 disconnected, 1 connected (default). Some devices give dis- 
tinguishable line styles for other small integers. 

-s Save screen, don’t erase before plotting. 

-x [ 1 ] lower [ upper [ spacing ] ] 

If 1 is present x axis is logarithmic, lower mdupper are lower (and upper) x limits, spacing, if 
present is grid spacing on x axis. Normally these quantities are determined automatically. 

— y [ I ] lower [ upper [ spacing ] ] 

If 1 is present y axis is logarithmic, lower mdupper are lower (and upper) y limits, spacing, if 
present is grid spacing on y axis. Normally these quantities are determined automatically. 

— h fraction 

is fraction of space for height. 

— w fraction 

is fraction of space for width. 

-r fraction 

is fraction of space to move right before plotting. 

-u fraction 

is fraction of space to move up before plotting. 

-t Transpose horizontal and vertical axes. (Option -x now applies to the vertical axis.) 
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If a specified lower limit exceeds the upper limit, the axis is reversed. 

SEE ALSO 

spline(lG), plot(lG) 

BUGS 

Graph stores all points internally and drops those for which there isn’t room. 
Segments that run out of bounds are dropped, not windowed. 

Logarithmic axes may not be reversed. 


Sun Release 3.0 


Last change: 1 June 1983 


149 



GREP(l) 


USER COMMANDS 


GREP(l) 


NAME 

grep, egrep, fgrep - search a file for a pattern 
SYNOPSIS 

grep [ -v ] [ -c ] [ -1 ] [ -n ] [ -b ] [ -i ] [ -s ] [ -h ] [ -w ] [ -e ] expression filename . . . 

egrep [ — v ] [ — c ] [ — 1 ] [ — n ] [ — b ] [ — s ] [ — h ] [ expression \ -e expression | -f file ] 
filename . . . 

fgrep [ v ] [-x] [ — c ] [ — 1 ] [ — n ] [ — b ] [ — i ] [ — s ] [-h] 
strings \ -e strings | -f file ] filename . . . 

DESCRIPTION 

Commands of the grep family search the input files (standard input default) for lines matching a pattern. 
Normally, each line found is copied to the standard output Grep patterns are limited regular expressions in 
the style of ed( 1). Egrep patterns are full regular expressions including alternation. Fgrep searches for 
lines that contain one of the (newline-separated) strings. Fgrep patterns are fixed strings — no regular 
expression metacharacters are supported. 

In general, egrep is the fastest of these programs. 

Take care when using the characters $ * [ * | ( ) and \ in the expression as these characters are also mean- 
ingful to the Shell. Enclose the entire expression argument in single quotes ' ' if you need any of the above 
special characters in the expression. 

When any of the grep utilities is applied to more than one input file, the name of the file is displayed 
preceding each line which matches the pattern. The filename is not displayed when processing a single file, 
so if you actually want the filename to appear, use Idev/null as a second file in the list. 

OPTIONS 

-v Invert the search to only display lines that do not match. 

-x Display only those lines which match exactly — that is, only lines which match in their entirety 
( fgrep only). 

-c Display a count of matching lines. 

-1 List the names of files with matching lines (once) separated by newlines. 

-n Precede each line by its relative line number in the file. 

-b Precede each line by the block number on which it was found. This is sometimes useful in locat- 

ing disk block numbers by context. 

-i Ignore the case of letters in making comparisons — that is, upper and lower case are considered 
identical. This applies to grep and fgrep only. 

-s Work silently, that is, display nothing except error messages. This is useful for checking the error 
status. 

-h Do not display filenames. 

-w search for the expression as a word as if surrounded by ‘\<’ and ‘\>’, see ex(l). grep only. 

-e expression 

Same as a simple expression argument, but useful when the expression begins with a -. 

-f file Take the regular expression (egrep) or string list (fgrep ) from file. 

REGULAR EXPRESSIONS 

In the following description ‘character’ excludes newline: 

\ Is an escape character: \ followed by any single character other than newline matches that charac- 
ter. 

Anchored match: matches the beginning of a line. 
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$ Anchored match: matches the end of a line. 

0 (period) matches any character. 

c Where c is any single character not otherwise endowed with special meaning matches that charac- 
ter. 

[ string ] 

Character class: match any single character from string. Ranges of ASCII character codes may be 
abbreviated as in ‘a-zO-9’. A ] may occur only as the first character of the string. A literal - 
must be placed where it can’t be mistaken as a range indicator. A A (circumflex) character 
immediately after the open bracket negates the sense of the character class, that is, the pattern 
matches any character except those in the character class. 

* Closure: a regular expression followed by an * (asterisk) matches a sequence of 0 or more 
matches of the regular expression. 

+ Closure: a regular expression followed by a + (plus) matches a sequence of 1 or more matches of 
the regular expression. 

? Closure: a regular expression followed by a ? (question mark) matches a sequence of 0 or 1 
matches of the regular expression. 

concatenation 

Two regular expressions concatenated match a match of the first followed by a match of the 
second. 

1 Alternation: two regular expressions separated by | or newline match either a match for the first or 
a match for the second ( egrep only). 

() A regular expression enclosed in parentheses matches a match for the regular expression. 

The order of precedence of operators at the same parenthesis level is [ ] (character classes), then * + ? (clo- 
sures), then concatenation, then | (alternation) and newline. 

EXAMPLES 

Search a file for a fixed string using fgrep: 

tutorial% fgrep intro /usr/man/man3/*.3* 

Look for character classes using grep: 

tutorial% grep ’[1-8]([CJMSNX])’ /usr/man/manl/*.l 

Look for alternative patterns using egrep: 

tutorial% egrep ’(Sally|Fred) (Smith|Jones|Parker)’ telephone.list 

To get the filename displayed when only processing a single file, use /dev/null as the second file in the list 
tutorial% grep ’Sally Parker’ telephone.list /dev/null 

SEE ALSO 


vi(l) 

visual display-oriented editor based on ex(l) 

ex(l) 

line-oriented text editor based on ed(l) 

ed(l) 

primitive line-oriented text editor 

sed(l) 

stream editor 

awk(l) 

pattern scanning and text processing language 

sh(l) 

Bourne Shell 


DIAGNOSTICS 

Exit status is 0 if any matches are found, 1 if none, 2 for syntax errors or inaccessible files. 

BUGS 

Lines are limited to 256 characters; longer lines are truncated. 
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Ideally there should be only one grep. 
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NAME 

groups - show group memberships 

SYNOPSIS 

groups 

DESCRIPTION 

Groups displays the groups to which you belong. Each user belongs to a group specified in the password 
file letc/passwd and possibly to other groups as specified in the file letcl group. If you do not own a file but 
belong to the group which it is owned by then you are granted group access to the file. 

When a new file is created it is given the group of the containing directory. 

SEE ALSO 

setgroups(2) 

FILES 

/etc/passwd, /etc/group 
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NAME 

head - display first few lines of specified files 
SYNOPSIS 

head [ -count] [file ... ] 

DESCRIPTION 

Head copies the first count lines of the specified file(s), or of the standard input if no filename is given, to 
the standard output. The default value of count is 10 lines. 

When more than one file is specified, head places a marker at the start of each file which looks like: 

==> filename <== 

Thus, a common way to display a set of short files, identifying each one, is: 
gaia% head -9999 filel file2 . . . 

EXAMPLE 

gaia% head -4 /usr/man/manl/{cat, head, tail}. 1 
==> /usr/man/manl/cat.l <== 

.TH CAT 1"2 June 1983" 

.SHNAME 

cat - concatenate and display 
.SH SYNOPSIS 

==>/usr/man/manl/head.l <== 

.TH HEAD 1 "24 August 1983” 

.SHNAME 

head - display first few lines of specified files 
.SH SYNOPSIS 

==>/usr/man/manl/tail.l <== 

.TH TAIL 1 ”27 April 1983" 

.SHNAME 

tail - display the last part of a file 
.SH SYNOPSIS 

SEE ALSO 

more(l), tail(l), cat(l) 
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NAME 

help - ask for help 

SYNOPSIS 

/usr/sccs/help [args] 

DESCRIPTION 

Help finds information to explain a message from a command or explain the use of a command. Zero or 
more arguments may be supplied. If no arguments are given, help will prompt for one. 

The arguments may be either message numbers (which normally appear in parentheses following mes- 
sages) or command names, of one of the following types: 

type 1 Begins with non-numerics, ends in numerics. The non-numeric prefix is usually 
an abbreviation for the program or set of routines which produced the message 
(for example, ge6, for message 6 from the get command). 

type 2 Does not contain numerics (as a command, such as get) 
type 3 Is all numeric (for example, 212) 

The response of the program will be the explanatory information related to the argument, if there is any. 
When all else fails, try /usr/sccs/help stuck. 

FILES 

/usr/lib/help directory containing files of message text 

DIAGNOSTICS 

Use help 1 1) for explanations. 
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NAME 

hostid - print identifier of current host system 

SYNOPSIS 

hostid 

DESCRIPTION 

The hostid command prints the identifier of the current host in hexadecimal. This numeric value is unique 
across all Sun hosts. 

SEE ALSO 

gethostid(2) 
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NAME 

hostname - set or print name of current host system 
SYNOPSIS 

hostname [ nameofhost ] 

DESCRIPTION 

The hostname command prints the name of the current host, as given before the “login” prompt. The 
super-user can set the hostname by giving an argument; this is usually done in the startup script 
/etc/rc.local. 

SEE ALSO 

gethostname(2), sethostname(2) 
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NAME 

iconedit — create and edit icons and cursors 

SYNOPSIS 

iconedit [filename ] 

OPTIONS 

iconedit accepts the SunWindows generic tool arguments; see suntools(l) for a list of these arguments. 
DESCRIPTION 

iconedit is a bitmap editor that allows you to create small images such as icons and cursors, iconedit runs 
in the SunWindows environment and can be positioned and manipulated in the same way as any other 
SunWindows tool. For general hints on using SunWindows tools, see suntools( 1). 

When invoked, iconedit displays a window consisting of several subwindows: 

• A large drawing area or canvas (on the left). 

• A small proof area for previewing a life-size version of the image being edited (at the lower right). 

• A control panel showing the options available and their current state. 

• An area for status messages (at the upper right). 

Instructions for the use of the mouse appear above the canvas. 

Move the cursor to the canvas, press and hold the left mouse button, and move the mouse as desired to 
draw an image. As you draw, an enlarged version of the image appears in the canvas, while a life-sized 
version of the image appears in the preview area. To “erase” any unwanted portions of the image, press 
and hold the center mouse button while moving the mouse as desired. Clicking the right mouse button 
inside the canvas will undo the previous operation. 

If you are editing a cursor image, move the cursor into the proof area to turn the proof image into the 
mouse cursor. This effect only lasts while you are in the proof area; it allows you to test how the new cur- 
sor looks during “real” use. 

Note that in this writeup, the term “cursor” refers to the mouse cursor, while the term “caret” indicates 
the current type-in position. 

CONTROL PANEL 

The control panel at the center right of the tool window lists the options available to you. 

To select an option, position the cursor on the desired item and click the left mouse button. 

To display a menu for an item, position the cursor on the desired item, then press and hold the right mouse 
button. To select an alternative from the menu, point at the desired alternative and release the mouse but- 
ton. If you are just starting out, you may want to use the menus until you become familiar with the tool. 

Some of the panel options are buttons which you press, in effect, by pointing to them and clicking the left 
mouse button. Load and Store are two examples of buttons. A small capsule-shaped box encloses each 
button. 

Other choices give you a set of alternatives from which to select. You can cycle through a set of alterna- 
tives for a given item by pointing to the item label and repeatedly clicking the left mouse button. 

The “painting hand” indicates the current painting mode. Small triangular carets indicate the current state 
of the Size and grid options as well as the proof background pattern. A triangular caret points to the 
current type-in position; this can be either the File field or the Fill field corresponding to the Text (“abc”) 
painting mode (see below). 

In detail, the control panel options are: 

File Contains the name of the file where the current image resides. To use a different file from the one 
shown, point at the file name, click the left mouse button, and type a new file name. The filename 
defaults to the filename given on the command line. 
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Entenng an alphabetic string terminated by <ESC> requests filename completion, iconedit 
searches the current directory for files whose names begin with the string you entered. If the 
filename search locates only one file, that file will be loaded in. In addition, typing CTRL-L, 
CTRL-S, or CTRL-Q are equivalent to pressing the Load, Store, or Quit buttons, respectively. 
Load (Button) Load the canvas from the file named in the File field. 

Store (Button) Store the current image in the file named in the File field. 

Quit (Button) Terminate processing. Quitting requires a confirming click of the left mouse button. 

Size Alter the canvas size. Choices are icon size (64 x 64 pixels) or cursor size (16 x 16 pixels). 
Default is icon size. 


Grid Display a grid over the drawing canvas, or turn the grid off. Default is ‘ ‘grid off ’ . 
Clear (Button) Clear the canvas. 


Fill (Button) Fill canvas with current rectangular fill pattern. 

Invert (Button) Invert each pixel represented on the canvas. 

Paintbrush 

Select from among five modes of painting. The painting hand indicates the current painting mode. 
Point at the desired mode and click the left mouse button to move the painting hand. The current 
painting mode remains until you change it. Instructions for each painting mode appear above the 
canvas. The painting modes are: 

dot Paint a single dot at a time. 


line Draw a line. To draw a line on the canvas, point to the first endpoint of the line, and 
press and hold the left mouse button. While holding the button down, drag the cursor to 
the second endpoint of the line. Release the mouse button. 

rectangle 

Draw a rectangle. To draw a rectangle on the canvas, point to the first comer of the rec- 
tangle and press and hold the left mouse button. While holding the button down, drag the 
cursor to the diagonally opposite comer of the rectangle. Release the mouse button. 

In the control panel, the Fill field to the right of the rectangle indicates the current rectan- 
gle fill pattern. Any rectangles you paint on the canvas will be filled with this pattern. 

circle Draw a circle. To draw a circle on the canvas, point to the center of the circle, and press 
and hold the left mouse button. While holding the button down, drag the cursor to the 
desired edge of the circle. Release the mouse button. 

In the control panel, the Fill field to the right of the circle indicates the current circle fill 
pattern. Any circles you paint on the canvas will be filled with this pattern. 

abc Insert text. To insert text, move the painting hand to “abc” and type the desired text. 
Then move the cursor to the canvas and press and hold the left mouse button. A box will 
appear where the text is to go. Position the box as desired and release the mouse button. 

In addition, you can choose the font in which to draw the text. Point at the Fill field to 
the right of the “abc” and either click the left mouse button to cycle through the fonts 
available (watch the “abc” change as you do this), or press and hold the right mouse 
button to summon up a menu of fonts. 

Load This is the rasterop to be used when loading a file in from disk. See the SunWindows Reference 
Manual for more details on rasterops. 

Fill This is the rasterop to be used when filling the canvas. The source for this operation is the rectan- 
gle fill pattern, and the destination is the canvas. 


Proof This is the rasterop to be used when rendering the proof image. The source for this operation is 
the proof image, and the destination is the proof background. 
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Proof background 

The proof background can be changed to allow you to preview how the image will appear against 
a variety of patterns. The squares just above the proof area show the patterns available for use as 
the proof background pattern. To change the proof background, point at the desired pattern and 
click the left mouse button. 


SEE ALSO 

suntools(l) 

FILES 

/usr/bin/iconedit 
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NAME 

indent - indent and format C program source 
SYNOPSIS 

indent [ input-file [ output-file ] ] [-bad|-nbad] [-bap|-nbap] [-bbb|-nbbb] [~bc|-nbc] 
[ — bl ] [-br] [-cn] [-cdn] [-cdb|-ncdb] [-ce|-nce] [ -cin ] [ -clin ] [-dn] [ — di« ] 
[ -fcl | -nfcl ] [-in] [ -ip | -nip ] [-In] [-lcn] [ -lp | -nip ] [-pcs|-npcs] [-npro] 
[ — psl | -npsl ] [ -sc | -nsc ] [ -sob | -nsob ] [ -st ] [ -troff ] [ — v | -nv ] 

DESCRIPTION 

Indent is a C program formatter. It reformats the C program in the input-file according to the switches. 
The switches which can be specified are described below. They may appear before or after the file names. 

NOTE: If you only specify an input-file, the formatting is done ‘in-place’, that is, the formatted file is writ- 
ten back into input-file and a backup copy of input-file is written in the current directory. If input-file is 
named ‘/blah/blah/file’, the backup file is named file.IMA'. 

If output-file is specified, indent checks to make sure it is different from input-file. 

OPTIONS 

The options listed below control the formatting style imposed by indent. 

-bap,-nbap If -bap is specified, a blank line is forced after every procedure body. Default -nbap. 

-bad,-nbad If -bad is specified, a blank line is forced after every block of declarations. Default: 

-nbad. 

— bbb,— nbbb If — bbb is specified, a blank line is forced before every block comment. Default: 

-nbbb. 

-bc,-nbc If -be is specified, then a newline is forced after each comma in a declaration, -nbc 

turns off this option. The default is -be. 

-br,-bl Specifying -bl lines up compound statements like this: 

if (...) 

{ 

code 

} 

Specifying -br (the default) makes them look like this: 
if (...) { 
code 

) 

-cn The column in which comments on code start. The default is 33. 

-cd n The column in which comments on declarations start. The default is for these comments 

to start in the same column as those on code. 

-cdb,-ncdb Enables (disables) the placement of comment delimiters on blank lines. With this option 
enabled, comments look like this: 

/* 

* this is a comment 
*/ 

Rather than like this: 

/* this is a comment */ 

This only affects block comments, not comments to the right of code. The default is 
-cdb . 

— ce,— nee Enables (disables) forcing ‘else’s to cuddle up to the immediady preceeding *}’. The 

default is -ce . 

-tin Sets the continuation indent to be n. Continuation lines will be indented that far from 

the beginning of the first line of the statement Parenthesized expressions have extra 
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-clin 


-drt 


-di/2 


-fcl-nfcl 


-irt 

-ip, -nip 


-irt 

-npro 

-lp,-nlp 


-pcs , -npcs 
— psl , -npsl 


-sc,-nsc 

-sob,-nsob 


-st 

-T typename 


-troff 


indentation added to indicate the nesting, unless — lp is in effect — ci defaults to the same 
value as -i. 

Causes case labels to be indented n tab stops to the right of the containing switch state- 
ment. -cli0.5 causes case labels to be indented half a tab stop. The default is — cliO . 

Controls the placement of comments which are not to the right of code. The default -dl 
means that such comments are placed one indentation level to the left of code. Specify- 
ing -dO lines up these comments with the code. See the section on comment indentation 
below. 

Specifies the indentation, in character positions, from a declaration keyword to the fol- 
lowing identifier. The default is -dil6 . 

Enables (disables) the formatting of comments that start in column 1. Often, comments 
whose leading 7’ is in column 1 have been carefully hand formatted by the programmer. 
In such cases, -nfcl should be used. The default is -fcl. 

The number of spaces for one indentation level. The default is 4. 

Enables (disables) the indentation of parameter declarations from the left margin. The 
default is -ip . 

Maximum length of an output line. The default is 75. 

Causes the profile files, ‘7.indent.pro’ and ‘7.indent.pro’, to be ignored. 

Lines up code surrounded by parenthesis in continuation lines. If a line has a left paren 
which is not closed on that line, then continuation lines will be lined up to start at the 
character position just after the left paren. For example, here is how a piece of contin- 
ued code looks with -nip in effect: 

pi = first_procedure (second_procedure (p2, p3) , 
third_j3rocedure (p4, p5) ) ; 

With -lp in effect (the default) the code looks somewhat clearer: 

pi = firstj>rocedure (second_procedure (p2, p3), 

third_procedure (p4, p5) ) ; 

Inserting a couple more newlines we get: 

pi = f irst_procedure (second_procedure (p2, 

p3) , 

third__procedure (p4, 

p5) ) ; 

If true (-pcs) all procedure calls will have a space inserted between the name and the ’(’. 
The default is -npcs 

If true (-psl) the names of procedures being defined are placed in column 1 - their types, 
if any, will be left on the previous lines. The default is -psl 

Enables (disables) the placement of asterisks (‘*’s) at the left edge of all comments. 

If -sob is specified, indent will swallow optional blank lines. You can use this to get rid 
of blank lines after declarations. Default: -nsob 

Causes indent to take its input from stdin, and put its output to stdout. 

Adds typename to the list of type keywords. Names accumulate: -T can be specified 
more than once. You need to specify all the typenames that appear in your program that 
are defined by typedefs - nothing will be harmed if you miss a few, but the program 
won’t be formatted as nicely as it should. This sounds like a painful thing to have to do, 
but it’s really a symptom of a problem in C: typedef causes a syntactic change in the 
laguage and indent can’t find all typedefs. 

Causes indent to format the program for processing by troff. It will produce a fancy 
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listing in much the same spirit as vgrind. If the output file is not specified, the default is 
standard output, rather than formatting in place. 

-v,-nv -v turns on ‘verbose’ mode, -nv turns it off. When in verbose mode, indent reports 

when it splits one line of input into two or more lines of output, and gives some size 
statistics at completion. The default is -nv. 

FURTHER DESCRIPTION 

You may set up your own ‘profile’ of defaults to indent by creating a file called undent. pro in either your 
login directory or the current directory and including whatever switches you like. A ‘.indentpro’ in the 
current directory takes precedence over the one in your login directory. If indent is run and a profile file 
exists, then it is read to set up the program’s defaults. Switches on the command line, though, always over- 
ride profile switches. The switches should be separated by spaces, tabs or newlines. 

Comments 

Box comments. Indent assumes that any comment with a dash or star immediately after the start of com- 
ment (that is, 7*-’ or 7**’) is a comment surrounded by a box of stars. Each line of such a comment is 
left unchanged, except that its indentation may be adjusted to account for the change in indentation of the 
first line of the comment. 

Straight text. All other comments are treated as straight text. Indent fits as many words (separated by 
blanks, tabs, or newlines) on a line as possible. Blank lines break paragraphs. 

Comment indentation 

If a comment is on a line with code it is started in the ‘comment column’, which is set by the -c n command 
line parameter. Otherwise, the comment is started at n indentation levels less than where code is currently 
being placed, where n is specified by the -dn command line parameter. If the code on a line extends past 
the comment column, the comment starts further to the right, and the right margin may be automatically 
extended in extreme cases. 

Preprocessor lines 

In general, indent leaves preprocessor lines alone. The only reformmatting that it will do is to straighten up 
trailing comments. It leaves imbedded comments alone. Conditional compilation (#ifdef...#endif) is 
recognized and indent attempts to correctly compensate for the syntactic peculiarites introduced. 

C syntax 

Indent understands a substantial amount about the syntax of C, but it has a ‘forgiving’ parser. It attempts to 
cope with the usual sorts of incomplete and misformed syntax. In particular, the use of macros lifov 
tdefine forever for(;;) 
is handled properly. 

FILES 

./.indent.pro profile file 

7.indent.pro profile file 

BUGS 

Indent has even more switches than Is. 

A common mistake that often causes grief is typing: 
indent * . c 

to the shell in an attempt to indent all the C programs in a directory. This is probably a bug, not a feature. 
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NAME 

indxbib — make inverted index to a bibliography 

SYNOPSIS 

indxbib database ... 

DESCRIPTION 

Indxbib makes an inverted index to the named databases (or files) for use by lookbib(\) and refer (l). 
These files contain bibliographic references (or other kinds of information) separated by blank lines. 

A bibliographic reference is a set of lines, constituting fields of bibliographic information. Each field starts 
on a line beginning with a followed by a key-letter, then a blank, and finally the contents of the field, 
which may continue until the next line starting with 

Indxbib is a shell script that calls two programs: lusrlliblreferlmkey and lusr/lib/refer/inv. mkey truncates 
words to 6 characters, and maps upper case to lower case. It also discards words shorter than 3 characters, 
words among the 100 most common English words, and numbers (dates) < 1900 or > 2000. These parame- 
ters can be changed — see Refer — a Bibliography System in the Editing and Text Processing on the Sun 
Workstation document inv creates an entry file (.ia), a posting file (.ib), and a tag file (.ic), all in the work- 
ing directory. 

FILES 

x.ia, x.ib, x.ic, where x is the first argument, or if these are not present, then x.ig, x 
SEE ALSO 

" r e f e r " in Formatting Documents on the Sun Workstation 
refer(l), addbib(l), sortbib(l), roffbib(l), lookbib(l) 

BUGS 

Probably all dates should be indexed, since many disciplines refer to literature written in the 1800s or ear- 
lier. 
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NAME 

install - install files 
SYNOPSIS 

install [ — c ] [ -m mode ] [ -o owner ] [ -g group ] [ — s ] binary destination 
DESCRIPTION 

binary is copied to destination. If destination already exists, it is removed before binary is copied. If the 
destination is a directory then binary is copied into file destination/binary. 

install refuses to move a file onto itself. 

Note: install has no special privileges since it simply uses cp to copy files from one place to another. The 
implications of this are: 

• You must have permission to read binary. 

• You must have permission to copy into destination. 

• You must have permission to change the modes on the final copy of the file if you want to use the -m 
option to change modes. 

• You must be super-user if you want to use the -o option to change ownership. 

OPTIONS 

-c Copy binary instead of moving it. In fact, install always copies the file, but the -c option is 
retained for backwards compatibility with old system shell scripts which might otherwise break. 

— m mode 

Specifies a different mode for binary: the mode for destination is set to 755 by default 
-o owner 

Set the owner of the destination file to owner, destination is changed to owner root by default. 

-g group 

Set the group ownership of the destination file to group, destination is changed to group staff by 
default. 

-s Strip binary files after it is installed — only applicable to binary files in a.out( 5) format. 

SEE ALSO 

chmod(l), cp(l), mv(l), strip(l), chown(8) 

BUGS 

Should be possible to move multiple files at a time, like mv or cp. 

When the destination is a directory, install simply appends the entire source file name to the directory 
name, instead of using the source file name’s last component like mv or cp. 
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NAME 

join - relational database operator 
SYNOPSIS 

join [ -an ] [ -e string ] [ -j [1 1 2] m ] [ -o list ] [ -tc ] filenamel filename2 
DESCRIPTION 

join forms, on the standard output, a join of the two relations specified by the lines of filenamel and 
filename2 . If filenamel is the standard input is used. 

Filel and filenamel must be sorted in increasing ASCII collating sequence on the fields on which they are 
to be joined, normally the first in each line. 

There is one line in the output for each pair of lines in filenamel and filename2 that have identical join 
fields. The output line normally consists of the common field, then the rest of the line from filenamel , then 
the rest of the line from filename2 . 

Fields are separated by blanks, tabs or newlines. Multiple separators count as one, and leading separators 
are discarded. 

OPTIONS 

-an The parameter n can be one of the values: 

1 produce a line for each unpayable line in filenamel . 

2 produce a line for each unpairable line in filename2 . 

3 produce a line for each unpairable line in both filenamel and filename2 . 

The normal output is also produced. 

-e s Replace empty output fields by string . 

-jU\2]m 

The j may be immediately followed by n, which is either a ‘1’ or a ‘2’. If n is missing, the join is 
on the m’th field of both files. If n is present, the join is on the nz’th field of file n, and the first 
field of the other. Note that join counts fields from 1 instead of 0 like sort does. 

-o list Each output line comprises the fields specified in list, each element of which has the form n.m, 
where n is a file number and m is a field number. Note that join counts fields from 1 instead of 0 
like sort does. 

-tc Use character c as a separator (tab character). Every appearance of c in a line is significant. 

SEE ALSO 

sort(l), comm(l), awk(l), uniq(l), look(l) 

BUGS 

With default field separation, the collating sequence is that of sort -b ; with -t, the sequence is that of a 
plain sort. 

The conventions of join, sort, comm, uniq, look, and awk are wildly incongruous. 
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NAME 

kill - send a signal to a process, or terminate a process 
SYNOPSIS 

kill [ -sig ] processid . . . 

kill —I 

DESCRIPTION 

Kill | sends the TERM (terminate, 15) signal to the specified processes. If a signal name or number preceded 
by is given as first argument, that signal is sent instead of terminate. The signal names are listed by 
using the -1 option, and are as given in /usr/include/signal.h, stripped of the common SIG prefix. 

The terminate signal will kill processes that do not catch the signal, so kill -9 ... is a sure kill, as the 
KILL (9) signal cannot be caught. By convention, if process number 0 is specified, all members in the pro- 
cess group (that is, processes resulting from the current login) are signaled (but beware: this works only if 
you use sA(l); not if you use c$ft(l).) The killed processes must belong to the current user unless he is the 
super-user. 

To shut the system down and bring it up single user the super-user may send the initialization process a 
TERM (terminate) signal by ‘kill 1’; see init( 8). To force init to close and open terminals according to 
what is currently in /etc/ttys use ‘kill -HUP 1 ’ (sending a hangup, signal 1). 

The shell reports the process number of an asynchronous process started with (run in the background). 
Process numbers can also be found by using ps(l). 

Kill is built in to csh(iy, it allows job specifiers, such as kill % .... in place of kill arguments. See csA(l) 
for details. 

OPTIONS 

-1 Display a list of signal names. 

SEE ALSO 

csh(l), ps(l), kill(2), sigvec(2) 

BUGS 

An option to kill process groups should be provided; a replacement for kill 0 for csh(l) users should be 
provided. 
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NAME 

last - indicate last logins of users and teletypes 
SYNOPSIS 

last [ —number ][ — f filename ] [ name ...] [tty ... ] 

DESCRIPTION 

last looks back in the wtmp file which records all logins and logouts for information about a user, a teletype 
or any group of users and teletypes. Arguments specify names of users or teletypes of interest. Names of 
teletypes may be given fully or abbreviated. For example ‘last 0’ is the same as ‘last ttyO’. If multiple 
arguments are given, the information which applies to any of the arguments is printed. For example ‘last 
root console’ would list all of "root’s" sessions as well as all sessions on the console terminal, last displays 
the sessions of the specified users and teletypes, most recent first, indicating the times at which the session 
began, the duration of the session, and the teletype which the session took place on. If the session is still 
continuing or was cut short by a reboot, last so indicates. 

The pseudo-user reboot logs in at reboots of the system, thus 

last reboot 

will give an indication of mean time between reboot. 

last with no arguments displays a record of all logins and logouts, in reverse order. 

If last is interrupted, it indicates how far the search has progressed in wtmp. If interrupted with a quit signal 
(generated by a controls) last indicates how far the search has progressed so far, and the search continues. 

OPTIONS 

—number 

limit the number of entries displayed to that specified by number. 

— f filename 

Use filename as the name of the accounting file instead of lusrladmlwtmp. 

FILES 

/usr/adm/wtmp login data base 

SEE ALSO 

utmp(5), ac(8), lastcomm(l) 
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NAME 

lastcomm - show last commands executed in reverse order 
SYNOPSIS 

lastcomm [ command name ] ... [user name] ... [terminal name] ... 

DESCRIPTION 

Lastcomm gives information on previously executed commands. Lastcomm with no arguments displays 
information about all the commands recorded during the current accounting file’s lifetime. If called with 
arguments, lastcomm only displays accounting entries with a matching command name, user name, or ter- 
minal name. 

EXAMPLES 

tutorial% lastcomm a.out root ttydO 

would produce a listing of all the executions of commands named a. out, by user root while using the termi- 
nal ttydO. and 

tutorial% lastcomm root 

would produce a listing of all the commands executed by user root. 

For each process entry, lastcomm displays the following items of information: 

• The command name under which the process was called. 

• One or more flags indicating special information about the process. The flags have the following mean- 
ings: 

F The process performed a fork but not an exec . 

S The process ran as a set-user-id program. 

D The process dumped memory. 

X The process was killed by some signal. 

• The name of the user who ran the process. 

• The terminal which the user was logged in on at the time (if applicable). 

• The amount of CPU time used by the process (in seconds). 

• The date and time the process exited. 

FILES 

/usr/adm/acct accounting file 

SEE ALSO 

last(l), acct(5), core(5) 
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NAME 

Id - link editor 
SYNOPSIS 

Id [ -A name ] [ -D hex ] [ -d ] [ -e entry ] [ -Lx ] [ -M ] [ -N ] [ -n ] [ -o name ] [ -r ] 

[ -S ] [ -s ] [ -Ttext hex ] [ -Tdata hex ] [ -t ] [ -u name ] [ -X ] [ -x ] 

[ -y sym ] [ -z ] filename . . . 

DESCRIPTION 

Id combines several object programs into one, resolves external references, and searches libraries. In the 
simplest case several object filename s are given, and Id combines them, producing an object module which 
can either be executed or become the input for a subsequent Id run. In the latter case, the -r option must be 
given to preserve the relocation bits. The output of Id is left on a file called a. out if not otherwise specified. 
The output file is made executable only if no errors occurred during link editing. 

Files specified by the argument filename ... are concatenated in the order specified. The entry point of the 
output is the beginning of the first routine, unless the -e option is specified. 

If a named file is a library, it is searched exactly once at the point it is encountered in the argument list. 
Only those routines defining an unresolved external reference are loaded. If a routine from a library refer- 
ences another routine in the same library, and the library has not been processed by ranlib, the referenced 
routine must appear after the referencing routine in the library. Thus the order of programs within libraries 
may be important. The first member of a library should be a file named ‘ .SYMDEF’, which is under- 

stood to be a dictionary for the library as produced by ranlib ; the dictionary is searched iteratively to 
satisfy as many references as possible. 

The symbols _etext, _edata and _end (etext, edata and end in C) are reserved, and if referred to, are set to 
the first location above the program, the first location above initialized data, and the first location above all 
data, respectively. It is erroneous to define these symbols. 

OPTIONS 

Options should appear before the filenames, except abbreviated library names specified by the -1 option, 
which can appear anywhere. 

-A name 

Incremental loading: linking is to be done in a manner so that the resulting object may be read into 
an already executing program. Name is the name of a file whose symbol table is taken as a basis 
on which to define additional symbols. Only newly linked material is entered into the text and 
data portions of a. out, but the new symbol table will reflect all symbols defined before and after 
the incremental load. This argument must appear before any other object file in the argument list. 
One or both of the -T option may be used as well, and will be taken to mean that the newly linked 
segment will commence at the corresponding addresses (which must be a multiple of the page 
size). The default value is the old value of _end. 

-D hex Pad the data segment with zero bytes to make it hex bytes long. 

-d Force definition of common storage even if the -r flag is present. 

— e entry 

Define the entry point: the entry argument is made the name of the entry point of the loaded pro- 
gram. 

-lx This option is an abbreviation for the library name ‘/lib/libx.a’, where x is a string. If that does not 
exist, Id tries ‘/usr/lib/libx.a’. A library is searched when its name is encountered, so the place- 
ment of a -1 is significant. 

-M Produce a primitive load map, listing the names of the files which will be loaded. 

-N Do not make the text portion read-only or sharable. (Use ‘magic number’ 0407.) 

-n Arrange (by giving the output file a 0410 ‘magic number’) that when the output file is executed, 

the text portion will be read-only and shared among all processes executing the file. This involves 
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moving the data areas up to the first possible segment boundary following the end of the text. 

-o name 

Name is made the name of the Id output file, instead of a.out. 

— r Generate relocation bits in the output file so that it can be the subject of another Id run. This flag 
also prevents final definitions from being given to common symbols, and suppresses the 
‘undefined symbol’ diagnostics. 

— S Strip the output by removing all symbols except locals and globals. 

-s Strip the output, that is, remove the symbol table and relocation bits to save space (but impair the 
usefulness of the debuggers). This information can also be removed by strip( 1). 

— Ttext hex 

Start the text segment at location hex. Specifying a bare -T is the same as using the -Ttext 
option. 

— Tdata hex 

Start the data segment at location hex. This option is only of use to programmers wishing to write 
code for PROM s, since the resulting code cannot be executed by the UNIX system. 

-t Trace: display the name of each file as it is processed. 

— u name 

Enter name as an undefined symbol. This is useful for loading wholly from a library, since ini- 
tially the symbol table is empty and an unresolved reference is needed to force the loading of the 
first routine. 

-X Record local symbols, except for those whose names begin with ‘L’. This option is used by cc to 
discard internally-generated labels while retaining symbols local to routines. 

-x Preserve only global (non- .globl) symbols in the output symbol table; only enter external sym- 
bols. This option saves some space in the output file. 

-ysym Display each file in which sym appears, its type and whether the file defines or references it. 
Many such options may be given to trace many symbols. It is usually necessary to begin sym with 
an as external C, FORTRAN and Pascal variables begin with underscores. 

-z Arrange for the process to be loaded on demand from the resulting executable file (0413 ‘magic 
number’) rather than preloaded. This is the default Results in a page-sized header on the output 
file followed by a text and data segment, each of which has a multiple of page-size bytes (being 
padded out with nulls in the file if necessary). With this format the first few BSS segment symbols 
may actually end up in the data segment; this is to avoid wasting the space resulting from round- 
ing the data segment size. The text is read-only and shared among all processes executing the file. 

FILES 

/lib/lib*. a libraries 

/usr/lib/lib* .a more libraries 

/usr/local/lib/lib*.a still more libraries 
a.out output file 

SEE ALSO 

as(l), ar(l), cc(l), ranlib(l), strip(l) 

BUGS 

There is no way to force data to be page-aligned. 
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NAME 

leave - remind you when you have to leave 

SYNOPSIS 

leave [[+]hhmm] 

DESCRIPTION 

Leave sets an alarm to a time you specify and will tell you when the time is up. Leave waits until the 
specified time, then reminds you that you have to leave. You are reminded 5 minutes and 1 minute before 
the actual time, at the time, and every minute thereafter. Leave disappears after you log off. 

You can specify the time in on of two ways, namely as an absolute time of day in the form hhmm where hh 
is a time in hours (on a 12 or 24 hour clock), or you can place a + sign in front of the time, in which case 
the time is relative to the current time, that is, the specified number of hours and minutes from now. All 
times are converted to a 12 hour clock, and assumed to be in the next 12 hours. 

If no argument is given, leave prompts with "When do you have to leave?”. Leave exits if you just type a 
newline, otherwise the reply is assumed to be a time. This form is suitable for inclusion in a .login or 
.profile. 

Leave ignores interrupts, quits, and terminates. To get rid of it you should either log off or use kill -9 and 
its process id. 

SEE ALSO 

calendar(l) 

EXAMPLES 

The first example sets the alarm to an absolute time of day: 
tutorial% leave 1535 
Alarm set for Wed Mar 7 15:35:07 1984 

work work work work 

tutorial% Time to leave! 

The second example sets the alarm for 10 minutes in the future: 
tutorial% leave +10 

Alarm set for Wed Mar 7 15:45:24 1984 
work work work work 
tutorials Time to leave! 

work work work work 
tutorial% You’re going to be late! 


BUGS 

Relative time does not work as described. Currently you must specify relative time in the form +mmmm. 
It is not checked against a 12 hour clock. 


172 


Last change: 7 March 1984 


Sun Release 3.0 



LEX ( 1 ) 


USER COMMANDS 


LEX(l) 


NAME 

lex - generator of lexical analysis programs 
SYNOPSIS 

lex [ -tvfn ] [ file ] . . . 

DESCRIPTION 

Lex generates programs to be used in simple lexical analyis of text The input files (standard input default) 
contain regular expressions to be searched for, and actions written in C to be executed when expressions 
are found. 

A C source program, ’lex.yy.c’ is generated, to be compiled thus: 
cc lex.yy.c 

This program, when run, copies unrecognized portions of the input to the output, and executes the associ- 
ated C action for each regular expression that is recognized. 

OPTIONS 

-t Place the result on the standard output instead of in file lex.yy.c . 

-v Print a one-line summary of statistics of the generated analyzer. 

— n Opposite of — v; — n is default. 

-f ‘Faster’ compilation: don’t bother to pack the resulting tables; limited to small programs. 
EXAMPLE 

lex lexcommands 

would draw lex instructions from the file lexcommands, and place the output in lex.yy.c 


%% 

[A-Z] putchar(yytext[0]+V-'A'); 

[]+$ 

[ ]+ putchar(' '); 

is an example of lex . This program converts upper case to lower, removes blanks at the end of lines, and 
replaces multiple blanks by single blanks. 

SEE ALSO 

yacc(l), sed(l) 

The paper, LEX — A Lexical Analyzer Generator, in the Sun Programming Tools Manual. 
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NAME 

lint — a C program verifier 
SYNOPSIS 

lint [ — abchnuvxz ] [ — D name=def\ [ — D name ] [ — U name ] [ —I dir ] filename . . . 
lint [ -C lib ] filename . . . 

DESCRIPTION 

lint attempts to detect features of the C program files that are likely to be bugs, non-portable, or wasteful. 
lint also checks the type usage of the program more strictly than the C compiler, lint runs the C preproces- 
sor as its first phase. 

Among the things which are currently found are unreachable statements, loops not entered at the top, 
automatic variables declared and not used, and logical expressions whose values are constant. Moreover, 
the usage of functions is checked to find functions which return values in some places and not in others, 
functions called with varying numbers of arguments, and functions whose values are not used. 

By default, it is assumed that all the files are to be loaded together; they are checked for mutual compatibil- 
ity. Function definitions for certain libraries are available to lint; these libraries are referred to by a con- 
ventional name, such as -lm, in the style of W( 1). The standard C library (-lc) is lint’s d by default. 
Arguments ending in .In are also treated as library files. 

To create lint libraries, use the -C option. For example 

tutorial% lint -Ccongress files . . . 

where files are the C sources of library congress, produces a file llib-lcongress .In in the current directory in 
the correct library format suitable for lint’ ing programs using -lcongress. 

General Comments 

The routine exit (2) and other functions which do not return are not understood; this causes various lies. 
Certain conventional comments in the C source will change the behavior of lint: 

/*NOTREACHED*/ 

at appropriate points stops comments about unreachable code. 

/*VARARGSn*/ 

suppresses the usual checking for variable numbers of arguments in the following function 
declaration. The data types of the first n arguments are checked; a missing n is taken to be 0. 

/*ARGSUSED*/ 

turns on the -v option for the next function. 

/*LINTLIBR ARY */ 

at the beginning of a file, shuts off complaints about unused functions in this file. 

OPTIONS 

a Report assignments of long values to int variables. 

b Report break statements that cannot be reached. This is not the default because, unfortunately, 
most lex(\) and many yacc(l) outputs produce dozens of such messages. 

c Complain about casts which have questionable portability. 

h Apply a number of heuristic tests to attempt to intuit bugs, improve style, and reduce waste, 

n Do not check compatibility against the standard library. 

u Do not complain about functions and variables used and not defined, or defined and not used (this 
is suitable for running lint on a subset of files comprising part of a larger program). 

v Suppress complaints about unused arguments in functions. 

x Report variables referred to by extern declarations, but never used. 

z Do not complain about structures that are never defined (for example, using a structure pointer 
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without knowing its contents). 

— D name-def 
—Dname 

Define name to the preprocessor, as if by ‘#define’. If no definition is given, the name is defined 
as "1". 

-U name 

Remove any initial definition of name in the preprocessor. 

“I dir ‘tinclude’ files whose names do not begin with 7’ are always sought first in the directory of the 
file argument, then in directories named in -I options, then in the lusr/include directory. 

-Clib create a lint library with name lib (see DESCRIPTION section). 

-1 Hb use lint library lib from the lusrllib/lint directory. 

EXAMPLE 

The following lint call: 

tutorial% lint -b myfile 

checks the consistency of the file ‘myfile’. The -b option indicates that unreachable break statements are 
to be checked for. 

FILES 

/usr/lib/lint/lint[l 2] programs 

/ usr/lib/lint/llib-1* . In Various prebuilt lint libraries. 

/usr/lib/lint/llib-1* Sources of the prebuilt lint libraries. 

These libraries exist for -lc, -lcore, -Icurses, -lm, -Imp, -lpixrect, -lsuntool and -lsunwindow. 

SEE ALSO 

cc(l), cpp(l) 

Lint, a C Program Checker, in Programming Tools for the Sun Workstation 

BUGS 

There are some things you just can’t get lint to shut up about. 
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NAME 

In - make links 
SYNOPSIS 

In [ -f ] [ -s ] filename [ linkname ] 
In [ -f ] [ -s ] filename . . . directory 


DESCRIPTION 

In assigns an additional name (directory entry), called a link, to a file or directory. Several links may be 
assigned to a file at any one time. The number of links does not affect other attributes such as size, protec- 
tions, data, etc. There are two kinds of links: hard links and symbolic links. 

A hard link, which is the default, can only be made to an existing file. Only the superuser can make a hard 
link to a directory. To remove a file with more than one hard link, all such links (including the name by 
which it was created) must be removed. Hard links may not span file systems. 

In can also make symbolic links. A symbolic link contains the name of the file or directory to which it is 
linked. The referenced file or directory is used when an open( 2) operation is performed on the link. A stat 
on a symbolic link returns the linked-to file; an lstat( 2) must be done to obtain information about the link 
itself. The readlink(2) call may be used to read the contents of a symbolic link. Symbolic links may span 
file systems and may refer to directories. 

Filename is the original name of the file or directory to be linked. Linkname is the new name to be associ- 
ated with the file or filename. If linkname is omitted, the last component of the original pathname is used. 
Directory is a directory in which to place the link. When a directoiy is specified, In uses the last com- 
ponent of each original pathname as the name of each link. 

OPTIONS 

-f Force a hard link to a directory, — this option is only available to the superuser. 

-s create symbolic links. 


EXAMPLES 

The commands below illustrate the effects of the 
tutorial% Is -F 
grab jones/ 

tutorial% Is -F jones 
house 

tutorial% In grab 
./grab: File exists 
tutorial% In jones/house 
tutorial% Is -F 
grab house jones/ 

tutorial% In grab hold 
tutorial% Is -F 

grab hold house jones/ 

tutorial^ In grab hold jones 
tutorial% Is -F jones 

grab hold house 

tutorial% 


different forms of the In command. 

See what files we’ve got 

See what files there are in jones 
One file 

try to link a file in the same directory 
Sorry — can’t link a file to itself 
link a file from another directory to here 


link a file to another name in this directory 


link files from here to jones 


SEE ALSO 

rm(l), cp(l), mv(l), link(2), readlink(2), stat(2), symlink(2), lstat(2) 

BUGS 

Error messages print the wrong file name when the -s option is used. 
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NAME 

lockscreen - maintain window context until “login” 

SYNOPSIS 

lockscreen [ — e ] [ — n ] [ — r ] 

DESCRIPTION 

Lockscreen preserves the user’s window setup and context when the machine is not in use. When run, the 
dark lockscreen display and constantly moving Sun Microsystems logo limit phosphorus bum of the video 
display that might otherwise occur from running the same window configuration for a long time. 

Lockscreen is executed from a terminal emulator running inside the SunWindows system. When any key- 
board or mouse button is pressed, the dark screen is replaced by an option panel that displays the user 
name, a dark box, and a prompt for the user’s password. If the user has no password, or if the — n option is 
used, the user’s window setup is immediately restored. 

When the option screen appears: 

1) Enter the user’s password to return to the Sunwindows environment; this password is not echoed 
on the screen, or, 

2) Point to the black box and click the left button to return to the dark display. 

The panel also allows you to enter a different user name by pointing to the Name: field, clicking the left 
button, and typing in the name. You must then supply the appropriate password. 

OPTIONS 

-e Add the Exit Desktop choice to the options panel. If pointed to and clicked, the Sunwindows 
environment is exited and the cunrent user is logged out. 

— n No password is required to reenter the window environment. 

-r Allows use of the user name root. Normally, root is not accepted as a valid user name. 

SEE ALSO 

suntools(l), login(l) 
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NAME 

login - sign on 

SYNOPSIS 

login [ username ] 

DESCRIPTION 

login signs username on to the system initially; login may also be used at any time to change from one 
userid to another. 


When used with no argument, login requests a user name and password (if appropriate). Echoing is turned 
off (if possible) while typing the password. 

When successful, login updates accounting files, informs you of the existence of any mail, prints the mes- 
sage of the day, and displays the time you last logged in (unless you have a .hushlogin file in your home 
directory — mainly used by nonhuman users, such as uucp). 

login initializes the user and group IDs and the working directory, then starts a command interpreter shell 
(usually either Ibinlsh or Ibinlcsh according to specifications found in the file letc/passwd. (Argument 0 of 
the command interpreter is “-sh”, or more generally, the name of the command interpreter with a leading 
dash (“-”) prepended.) 

login also initializes the environment with information specifying home directory, command interpreter, 
terminal-type (if available) and username. 

If the file letc/nologin exists, login prints its contents on the user’s terminal and exits. This is used by shut- 
down^) to stop logins when the system is about to go down. 

The login command, recognized by sh and csh, is executed directly (without forking), and terminates that 
shell. To resume working, you must log in. 

login times out and exits if its prompt for input is not answered within a reasonable time. 

When the Bourne Shell (sh) starts up, it reads a file called .profile from your home directory (that of the 
username you use to log in). When the C-Shell (csh) starts up, it reads a file called .cshrc from your home 
directory, and then reads a file called .login. 

The Shells read these files only if they are owned by the person logging in. 


FILES 

letclutmp 

lusrladmlwtmp 

lusrladmllastlog 

lusrlttytype 

lusrlspoollmaill* 

letc/motd 

letc/passwd 

I etc! nolo gin 

7 . hushlogin 


accounting 
accounting 
time of last login 
terminal types 
mail 

message-of-the-day 
password file 
stop login, print message 
makes login quieter 


SEE ALSO 

init(8), getty(8), mail(l), passwd(l), passwd(5), environ(5), shutdown(8), utmp(5) 


DIAGNOSTICS 

“Login incorrect,” if the name or the password is bad (or mistyped). 

“No Shell”, “cannot open password file”, “no directory”: ask your system administrator for assistance. 
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NAME 

look - find lines in a sorted list 
SYNOPSIS 

look [ -df ] string [ file ] 

DESCRIPTION 

Look consults a sorted file and prints all lines that begin with string. 

OPTIONS 

-d ‘Dictionary’ order: only letters, digits, tabs and blanks participate in comparisons, 

-f Fold: Upper case letters compare equal to lower case. 

If no file is specified, look uses lusr/dictlwords with collating sequence -df. 

FILES 

/usr/dict/words 

SEE ALSO 

sort(l), grep(l) 
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NAME 

lookbib - find references in a bibliography 

SYNOPSIS 

lookbib database 

DESCRIPTION 

A bibliographic reference is a set of lines, constituting fields of bibliographic information. Each field starts 
on a line beginning with a followed by a key-letter, then a blank, and finally the contents of the field, 
which may continue until the next line starting with 

Lookbib uses an inverted index made by indxbib to find sets of bibliographic references. It reads keywords 
typed after the “>” prompt on the terminal, and retrieves records containing all these keywords. If nothing 
matches, nothing is returned except another “>” prompt. 

It is possible to search multiple databases, as long as they have a common index made by indxbib. In that 
case, only the first argument given to indxbib is specified to lookbib. 

If lookbib does not find the index files (the .i[abc] files), it looks for a reference file with the same name as 
the argument, without the suffixes. It creates a file with a ’.ig’ suffix, suitable for use with fgrep. Lookbib 
then uses this fgrep file to find references. This method is simpler to use, but the .ig file is slower to use 
than the .i[abc] files, and does not allow the use of multiple reference files. 

FILES 

x.ia, jc.ib, r.ic, where x is the first argument, or if these are not present, then x.ig, x 
SEE ALSO 

"refer" in Formatting Documents on the Sun Workstation 
refer(l), addbib(l), sortbib(l), roffbib(l), indxbib(l) 

BUGS 

Probably all dates should be indexed, since many disciplines refer to literature written in the 1800s or ear- 
lier. 
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NAME 

lorder - find ordering relation for an object library 
SYNOPSIS 

lorder file... 

DESCRIPTION 

Give lorder one or more object or library archive (see ar(l)) files, and it lists pairs of object file names — 
meaning that the first file of the pair refers to external identifiers defined in the second — to the standard 
output. Lorder ’s output may be processed by tsort( 1) to find an ordering of a library suitable for one-pass 
access by ld( 1). 

EXAMPLE 

This brash one-liner intends to build a new library from existing .o files, 
ar cr library ' lorder *.o | tsort' 

The ranlib(l), command converts an ordered archive into a randomly accessed library and makes lorder 
unnecessary. 

SEE ALSO 

tsort(l), ld(l), ar(l), ranlib(l) 

BUGS 

The names of object files, in and out of libraries, must end with ‘ .o’ ; otherwise, nonsense results. 
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NAME 

lpq — spool queue examination program 
SYNOPSIS 

*pq [ +[ num ] ] [ — 1 ] [ — P printer ] [ job #...][ user . . . ] 

DESCRIPTION 

lpq examines the spooling area used by lpd{ 8) for printing files on the line printer, and reports the status of 
the specified jobs or all jobs associated with a user. 

lpq reports on any jobs currently in the queue when invoked without any options. Arguments supplied that 
are not recognized as options are interpreted as user names or job numbers to filter out only those jobs of 
interest. 


For each job submitted (that is, each invocation of Ipr) lpq reports the user’s name, current rank in the 
queue, the names of files comprising the job, the job identifier (a number which may be supplied to Iprm 
for removing a specific job), and the total size in bytes. Normally, only as much information as will fit on 
one line is displayed. Job ordering is dependent on the algorithm used to scan the spooling directory and is 
supposed to be FIFO (First in First Out). File names comprising a job may be unavailable (when Ipr is 
used as a sink in a pipeline) in which case the file is indicated as ‘(standard input)’. 

If lpq warns that there is no daemon present (that is, due to some malfunction), the /pc (8) command can be 
used to restart the printer daemon. 


OPTIONS 

— P printer report the state of the queue to the specified printer. In the absence of the -P option, the queue 
to the printer specified by the PRINTER variable in the environment is reported on. If the PRINTER variable 
isn’t set, the default line printer queue is reported. 


-1 job#... 

causes information about each of the files comprising the job to be printed. 

+nnn display the spool queue until it empties. Supplying a number nnn immediately after the + sign 
indicates that lpq should sleep nnn seconds in between scans of the queue. 


FILES 

/etc/termcap 
/etc/printcap 
/usr/spool/* 
/usr/spool/*/cf* 
/usr/spool/ */lock 


for manipulating the screen for repeated display 

to determine printer characteristics 

the spooling directory, as determined from printcap 

control files specifying jobs 

the lock file to obtain the currently active job 


SEE ALSO 

lpr(l), lprm(l), lpc(8), lpd(8) 


BUGS 

The + option doesn’t wait until the entire queue is empty; it only waits until the local machine’s queue is 
empty. 


lpq may report unreliably. The status, as reported, may not always reflect the actual state of the printer. 
Output formatting is sensitive to the line length of the terminal; this can result in widely-spaced columns. 
lpq is sometimes unable to open various files because the lock file is malformed. 


DIAGNOSTICS 

Waiting for printer to become ready (offline ?) 

The daemon could not open the printer device. This can happen for a number of reasons; the most 
common is that the printer is turned off-line. This message can also be generated if the printer is 
out of paper, the paper is jammed, and so on. The actual reason is dependent on the meaning of 
error codes returned by system device driver. Not all printers supply sufficient information to dis- 
tinguish when a printer is off-line or having trouble (for example, a printer connected through a 
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serial line). Another possible cause of this message is some other process, such as an output filter, 
has an exclusive open on the device. Your only recourse here is to kill off the offending 
program(s) and restart the printer with Ipc. 

printer is ready and printing 

The Ipq program checks to see if a daemon process exists for printer and prints the file status. If 
the daemon is hung, a super user can use Ipc to abort the current daemon and start a new one. 
waiting for host to come up 

Indicates that there is a daemon trying to connect to the remote machine named host in order to 
send the files in the local queue. If the remote machine is up, Ipd on the remote machine is prob- 
ably dead or hung and should be restarted as mentioned for Ipr. 

sending to host 

The files should be in the process of being transferred to the remote host. If not, the local daemon 
should be aborted and started with Ipc. 

Warning: printer is down 

The printer has been marked as being unavailable with Ipc. 

Warning: no daemon present 

The Ipd process overseeing the spooling queue, as indicated in the “lock” file in that directory, 
does not exist This normally occurs only when the daemon has unexpectedly died. The error log 
file for the printer should be checked for a diagnostic from the deceased process. To restart an 
Ipd, use 

% /usr/etc/Ipc restart printer 
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NAME 

lpr - off line print 
SYNOPSIS 

lpr [ -P printer ] [ —ttnum ] [ -C class ] [ -J job ] [ -T title ] [ -i [ num] ] [ -1234/on/ ] 

[-wnum ] [ -r ] [ -m ] [ -h ] [ -s ] [ -filter _option ] [filename . . . ] 

DESCRIPTION 

lpr uses a spooling daemon to print the named files when facilities become available, lpr reads the stndard 
input if no files are specified. 

OPTIONS 

-P printer 

Force output to the named printer . Normally, the default printer is used (site dependent), or the 
value of the PRINTER environment variable is used. 

-#num Produce multiple copies of output, using num as the number of copies for each file named. For 
example, 

tutorial% lpr -#3 new.index.c print.index.c more.c 
produces three copies of the file new. index. c , followed by three copies of print. index. c , etc. On 
the other hand, 

tutorial% cat new.index.c print.index.c more.c | lpr -#3 
generates three copies of the concatenation of the files. 

-C Print class as the job classification on the burst page. For example, 

tutorial% lpr -C Operations new.index.c 

replaces the system name (the name returned by hostname) with ‘Operations’ on the burst page, 
and prints the file new. index. c . 

—3 job Print job as the job name on the burst page. Normally, lpr uses the first file’s name. 

-T title Use title instead of the file name for the title used by pr. 

-i [num] Indent output num spaces. If num is not given, eight spaces are used as default 
-1 
-2 
-3 

-4 Mount the specified font on font position 1, 2, 3, or 4. The daemon will construct a .railmag file in 
the spool directory that indicates the mount by referencing lusrlliblvfontlfont. 

-y/num Use num as the page width for pr. 

-r Remove the file upon completion of spooling. 

-m Send mail upon completion. 

-h Suppress printing the burst page. 

-s Create a symbolic link from the spool area to the data files rather than trying to copy them (so 
large files can be printed). This means the data files should not be modified or removed until they 
have been printed. In the absence of this option, files larger than 1 Megabyte in length are trun- 
cated. Note that the -s option only works if you are specifically naming data files — it doesn’t 
work if lpr is at the end of a pipeline. 

filter _option 

The following single letter options notify the line printer spooler that the files are not standard text 
files. The spooling daemon will use the appropriate filters to print the data accordingly. 

-p Use pr to format the files (lpr -p is very much like pr | lpr). 

-1 Print control characters and suppress page breaks. 

-t The files contain data from troffi cat phototypesetter commands). 
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-n The files contain data from ditroff (device independent troff). 

-d The files contain data from tex (DVI format from Stanford). 

-g The files contain standard plot data as produced by the plot (3X) routines (see also 
plot (1G) for the filters used by the printer spooler). 

-v The files contain a raster image, see rasterfile(5). 

-c This option currently is unassigned. 

-f Interpret the first character of each line as a standard FORTRAN carriage control charac- 
ter. 

-h Postscript data. 


FILES 

/etc/passwd 

/etc/printcap 

/usr/lib/lpd* 

/usr/spool/* 

/usr/spool/ */cf* 

/usr/spool/*/df* 

/usr/spool/ */tf* 


personal identification 
printer capabilities data base 
line printer daemons 
directories used for spooling 
daemon control files 
data files specified in “cf” files 
temporary copies of “cf ’ files 


SEE ALSO 

lpq(l), lprm(l), pr(l), printcap(5), lpc(8), lpd(8), rasterfile(5), screendump(l) 
DIAGNOSTICS 


Ipr: copy file is too large 

A file is determined to be too ‘large’ to print by copying into the spool area. Use the -s option as 
defined above to make a symbolic link to the file instead of copying it. A ‘large’ file is approxi- 
mately 1 Megabyte in this system. 


Ipr: printer : unknown printer 

The printer was not found in the printcap database. Usually this is a typing mistake; however, it 
may indicate a missing or incorrect entry in the letclprintcap file. 

Ipr: printer : jobs queued, but cannot start daemon. 

The connection to Ipd on the local machine failed. This usually means the printer server started at 
boot time has died or is hung. Check the local socket Idevlprinter to be sure it still exists (if it 
does not exist, there is no Ipd process running). 

Ipr: printer : printer queue is disabled 

This means the queue was turned off with 

tutorial% /usr/etc/lpc disable printer 

to prevent Ipr from putting files in the queue. This is normally done by the system manager when 
a printer is going to be down for a long time. The printer can be turned back on by a super-user 
with Ipc. 


If the -f and -s flags are combined as follows: 


Ipr -fs filename 

copies the file to the spooling directory rather than making a symbolic link. 

Placing the -s flag first, or writing each as separate arguments makes a link as expected. 

BUGS 

Ipr -p is not equivalent to pr | Ipr. Ipr -p puts the current date at the top of each page, rather than the date 
last modified, and inserts a header page between each file printed. 

The — p and — # options don’t work well together; the second and subsequent copies do not include the file 
name in each page’s title. 
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Fonts for troff and tex reside on the host with the printer. It is currently not possible to use local font 
libraries. 
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NAME 

lprm - remove jobs from the line printer spooling queue 
SYNOPSIS 

lprm [ — P printer ] [ — ] [job # . . . ] [ username . . . ] 

DESCRIPTION 

lprm removes a job, or jobs, from a printer’s spool queue. Since the spooling directory is protected from 
users, using lprm is normally the only method by which a user may remove a job. 

lprm without any arguments will delete the currently active job if it is owned by the user who invoked 
lprm. 

If the - flag is specified, lprm will remove all jobs which a user owns. If the super-user employs this flag, 
the spool queue will be emptied entirely. The owner is determined by the user’s login name and host name 
on the machine where the Ipr command was invoked. 

Specifying a user’s name, or list of user names, will cause lprm to attempt to remove any jobs queued 
belonging to that user (or users). This form of invoking lprm is useful only to the super-user. 

A user may dequeue an individual job by specifying its job number. This number may be obtained from 
Ipq. For example: 

tutorial% Ipq -Pimagen 
imagen is ready and printing 

Rank Owner lob Files Total Size 

active wendy 385 standard input 35501 bytes 

tutorial% lprm -Pimagen 305 

lprm announces the names of any files it removes and is silent if there are no jobs in the queue which match 
the request list. 

lprm will kill off an active daemon, if necessary, before removing any spooling files. If a daemon is killed, 
a new one is automatically restarted upon completion of file removals. 

The -P option may be used to specify the queue associated with a specific printer (otherwise the default 
printer, or the value of the PRINTER variable in the environment is used). 

FILES 

/etc/printcap printer characteristics file 

/usr/spool/* spooling directories 

/usr/spool/*/Iock lock file used to obtain the pid of the current 

daemon and the job number of the currently active job 

SEE ALSO 

lpr(l), lpq(l), lpd(8) 

DIAGNOSTICS 

lprm: printer: cannot restart printer daemon 

The connection to Ipd on the local machine failed. This usually means the printer server started at 
boot time has died or is hung. Check the local socket /dev/printer to be sure it still exists (if it 
does not exist, there is no Ipd process running). Use 

tutorial% ps ax | fgrep Ipd 

to get a list of process identifiers of running lpd’s. The Ipd to kill is the one which is not listed in 
any of the “lock" files (the lock file is contained in the spool directory of each printer). Kill the 
master daemon using the following commands: 

tutorial% su Password: 
tutorial# kill pid 
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Then remove Idevlprinter and restart the daemon (and printer) with the following commands. 

tutorial# rm /dev/printer 
tutorial# /usr/lib/lpd 

Another possibility is that the Ipr program is not setuid root, setgid daemon. This can be checked 
with 

tutorial# Is -Ig /usr/ucb/lpr 

BUGS 

Since there are race conditions possible in the update of the lock file, the currently active job may be 
incorrectly identified. 
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NAME 

Is — list contents of directory 
SYNOPSIS 

Is [ -acdfgilqrstulACLFR ] filename . . . 

DESCRIPTION 

For each filename which is a directory, Is lists the contents of the directory; for each filename which is a 

file, Is repeats its name and any other information requested. By default, the output is sorted alphabetically. 

When no argument is given, the current directory is listed. When several arguments are given, the argu- 
ments are first sorted appropriately, but file arguments are processed before directories and their contents. 
OPTIONS 

-a List all entries; in the absence of this option, entries whose names begin with a V are not listed 
(except for the super-user, for whom Is normally prints even files that begin with a V). 

-c Use time of last edit (or last mode change) for sorting or printing. 

-d If argument is a directory, list only its name; often used with -1 to get the status of a directory. 

-f Force each argument to be interpreted as a directory and list the name found in each slot. This 

option turns off —I, — t, — s, and — r, and turns on —a; the order is the order in which entries appear 
in the directory. 

-g Show the group ownership of the file in a long output. 

— i For each file, print the i-number in the first column of the report. 

-1 List in long format, giving mode, number of links, owner, size in bytes, and time of last 

modification for each file. (See below.) If the file is a special file the size field will instead contain 
the major and minor device numbers. If the file is a symbolic link the pathname of the linked-to 
file is printed preceded by 

-q Display non-graphic characters in filenames as the character *?’; this is the default when output is 
to a terminal. 


-r Reverse the order of sort to get reverse alphabetic or oldest first as appropriate. 

-s Give size in kilobytes of each file. 

-t Sort by time modified (latest first) instead of by name. 

-u Use time of last access instead of last modification for sorting (with the -t option) and/or printing 

(with the -I option). 

-1 Force one entry per line output format; this is the default when output is not to a terminal. 

-A Same as -a, except that V and are not listed. 

-C Force multi-column output; this is the default when output is to a terminal. 

-F Mark directories with a trailing 7’, executable files with a trailing symbolic links with a trail- 
ing and AF_UNIX domain sockets with a trailing *=’. 

-L If argument is a symbolic link, list the file or directory the link references rather than the link 
itself. 

-R Recursively list subdirectories encountered. 

INTERPRETATION OF LISTING 

The mode printed under the -I option contains 11 characters interpreted as follows. If the first character is: 
d entry is a directory; 
b entry is a block-type special file; 
c entry is a character-type special file; 

1 entry is a symbolic link 
s entry is an AF UNIX domain socket, or 
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FILES 


BUGS 


- entry is a plain file. 

The next 9 characters are interpreted as three sets of three bits each. The first set refers to owner permis- 
sions; the next to permissions to others in the same user-group; and the last to all others. Within each set 
the three characters indicate permission respectively to read, to write, or to execute the file as a program. 
For a directory, ‘execute’ permission is interpreted to mean permission to search the directory. The per- 
missions are indicated as follows: 
r the file is readable; 
w the file is writable; 
x the file is executable; 

- the indicated permission is not granted. 

The group-execute permission character is given as s if the file has the set-group-id bit set; likewise the 
owner-execute permission character is given as s if the file has the set-user-id bit set. 

The last character of the mode (normally ‘x’ or *-’) is t if the 1000 bit of the mode is on. See chmod(\) for 
the meaning of this mode. 

When the sizes of the files in a directory are listed, a total count of blocks, including indirect blocks is 
printed. 

/etc/pass wd to get user id’ s for ‘Is -V. 

/etc/group to get group id’ s for ‘Is- g’ . 

Newline and tab are considered printing characters in filenames. 

The output device is assumed to be 80 columns wide. 

The option setting based on whether the output is a teletype is undesirable as l ls -s’ is much different than 
‘Is - s | lpr’. On the other hand, not doing this setting would make old shell scripts which used Is almost 
certain losers. 
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NAME 

m4 - macro processor 
SYNOPSIS 

m4 [file ... ] 

DESCRIPTION 

M4 is a macro processor intended as a front end for Ratfor, C, and other languages. Each argument file is 
processed in order; the standard input is read if there are no arguments or if an argument is The pro- 
cessed text is written on the standard output. 

Macro calls have the form 


name(argl,arg2, . . . , argn) 

The ‘(’ must immediately follow the name of the macro. If a defined macro name is not followed by a ‘(’, 
it is deemed to have no arguments. Leading unquoted blanks, tabs, and newlines are ignored while collect- 
ing arguments. Potential macro names consist of letters, digits, and underscore *_*, where the first charac- 
ter is not a digit. 

Left and right single quotes (' ') are used to quote strings. The value of a quoted string is the string stripped 
of the quotes. 

When a macro name is recognized, its arguments are collected by searching for a matching right 
parenthesis. Macro evaluation proceeds normally during the collection of the arguments, and any commas 
or right parentheses which happen to turn up within the value of a nested call are as effective as those in the 
original input text. After argument collection, the value of the macro is pushed back onto the input stream 
and rescanned. 


M4 makes available the following built-in macros. They may be redefined, but once this is done the origi- 
nal meaning is lost. Their values are null unless otherwise stated. 


define The second argument is installed as the value of the macro whose name is the first argument. 

Each occurrence of $n in the replacement text, where n is a digit, is replaced by the n ’th argu- 
ment. Argument 0 is the name of the macro; missing arguments are replaced by null strings. 

undefine removes the definition of the macro named in its argument. 

ifdef If the first argument is defined, the value is the second argument, otherwise the third. If there 
is no third argument, the value is null. The word unix is predefined on UNIX versions of m4. 


changequote 

Change quote characters to the first and second arguments. Changequote without arguments 
restores the original values (that is, ' '). 


M4 maintains 10 output streams, numbered 0-9. The final output is the concatenation of the 
streams in numerical order; initially stream 0 is the current stream. The divert macro changes 
the current output stream to its (digit-string) argument. Output diverted to a stream other than 
0 through 9 is discarded. 


undivert causes immediate output of text from diversions named as arguments, or all diversions if no 
argument. Text may be undiverted into another diversion. Undiverting discards the diverted 
text. 


divnum 

dnl 

ifelse 


incr 


returns the value of the current output stream. 

reads and discards characters up to and including the next newline. 

has three or more arguments. If the first argument is the same string as the second, then the 
value is the third argument. If not, and if there are more than four arguments, the process is 
repeated with arguments 4, 5, 6, 7 and so on. Otherwise, the value is either the last string not 
used by the above process, or, if it is not present, null. 

returns the value of its argument incremented by 1. The value of the argument is calculated by 
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interpreting an initial digit-string as a decimal number. 

eval evaluates its argument as an arithmetic expression, using 32-bit arithmetic. Operators include 
+, *, /, %, ' (exponentiation); relational; parentheses. 

len returns the number of characters in its argument. 

index returns the position in its first argument where the second argument begins (zero origin), or -1 
if the second argument does not occur. 

substr returns a substring of its first argument. The second argument is a zero origin number select- 
ing the first character; the third argument indicates the length of the substring. A missing third 
argument is taken to be large enough to extend to the end of the first string. 

translit transliterates the characters in its first argument from the set given by the second argument to 
the set given by the third. No abbreviations are permitted. 

include returns the contents of the file named in the argument. 

sinclude is identical to include, except that it says nothing if the file is inaccessible. 

syscmd executes the UNIX command given in the first argument. No value is returned. 

maketemp fills in a string of the form XXXXX in its argument with the current process id. 

errprint prints its argument on the diagnostic output file. 

dumpdef prints current names and definitions, for the named items, or for all if no arguments are given. 

SEE ALSO 

M4 — A Macro Processor , in Programming Tools for the Sun System. 
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NAME 

Mail - interactive message processing system 
SYNOPSIS 

Mail [ -d ] [ -e ] [ -f [filename | +folder ] ] [ — F ] [ — h number] [ — H ] [ — i ] [ — n ] 

[ -N ] [-r address] [-s subject] [ -T file ] [ -u user ] [-U] [-v] [name... ] 

DESCRIPTION 

mail provides a comfortable, flexible environment for sending and receiving messages electronically. 
When reading mail, mail provides commands to facilitate saving, deleting, and responding to messages. 
When sending mail, mail allows editing, reviewing and other modification of the message as it is entered. 

Incoming mail is stored in a standard file for each user, called the system mailbox for that user. When mail 
is called to read messages, the mailbox is the default place to find them. As messages are read, they are 
marked to be moved to a secondary file for storage, unless specific action is taken, so that the messages 
need not be seen again. This secondary file is called the mbox and is normally located in the user’s HOME 
directory (see ‘MBOX’ ( variables ) for a description of this file). Messages remain in this file until forcibly 
removed. 

OPTIONS 

On fire command line, options start with a dash (-) and any other arguments are taken to be destinations 
(recipients). If no recipients are specified, mail attempts to read messages from the mailbox. Command 
line options are: 

-d 
-e 

-f [ filename ] 

-f [+folder]" 

-F 

— h number 

-H 
-i 
-n 
-N 

— r address 
-s subject 
-T file 

— u user 
-U 

-v 

SENDING MAIL 

When sending mail, mail is in input mode. If no subject is specified on the command line, a prompt for the 
subject is printed. As the message is typed, mail reads the message and stores it in a temporary file. Com- 
mands may be entered by beginning a line with the tilde (') escape character followed by a single com- 
mand letter and optional arguments. See tilde escapes for a summary of these commands. 

READING MAIL 

When reading mail, mail is in command mode. A header summary of the first several messages is 
displayed, followed by a prompt indicating mail can accept regular commands (see commands below). 


Turn on debugging output. Neither particularly interesting nor recommended. 

Test for presence of mail. Mail prints nothing and exits with a successful return code if 
there is mail to read. 

Read messages from filename instead of mailbox. If no filename is specified, the mbox is 
used. 

Use the fil & folder in the ‘folders’ directory (as with the folder command). 

Record the message in a file named after the first recipient. Overrides the ‘record’ vari- 
able, if set (see variables). 

The number of network ‘hops’ made so far. This is provided for network software to 
avoid infinite delivery loops. 

Print header summary only. 

Ignore interrupts. See also ‘ignore’ ( variables ). 

Do not initialize from the system default Mail.rc file. 

Do not print initial header summary. 

Pass address to network delivery software. All tilde commands are disabled. 

Set the Subject header field to subject. 

Print the contents of the article-id fields of all messages that were read or deleted on file 
(for the use of network news programs if available). 

Read user’s mailbox. This is only effective if user’s mailbox is not read protected. 
Convert uucp style addresses to internet standards. Overrides the ‘conv’ environment 
variable. 

Pass the -v flag to sendmail($). 
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At any time, the behavior of mail is governed by a set of environment variables. These are flags and 
valued parameters which are set and cleared via the set and unset commands. See variables below for a 
summary of these parameters. 

Recipients listed on the command line may be of three types: login names, shell commands, or alias 
groups. Login names may be any network address, including mixed network addressing. If the recipient 
name begins with a pipe symbol (|), the rest of the name is taken to be a shell command to pipe the message 
through. This provides an automatic interface with any program that reads the standard input, such as Ipr 
for recording outgoing mail on paper. Alias groups are set by the alias command (see commands below) 
and are lists of recipients of any type. 

Regular commands are of the form 

[ command ] [ msglist ] [ arguments ] 

If no command is specified in command mode , that is, you just type a carriage-return, print is assumed. In 
input mode, commands are recognized by the escape character, and lines not treated as commands are 
taken as input for the message. 

Each message is assigned a sequential number, and there is at any time the notion of a ‘current’ message, 
marked by a V in the header summary. Many commands take an optional list of messages ( msglist ) to 
operate on, which defaults to the current message. A msglist is a list of message specifications separated by 
spaces, which may include: 

n Message number n. . The current message. 

The first undeleted message. 

$ The last message. 

+ The next undeleted message. 

- The previous undeleted message. 

* All messages. 

n-m An inclusive range of message numbers, 

user All messages from user. 

/string All messages with string in the subject line (case ignored). 

:c All messages of type c, where c is one of: 
d deleted messages 

n new messages 

o old messages 

r read messages 

u unread messages 

Note that the context of the command determines whether this type of message specification 
makes sense. 

Other arguments are usually arbitrary strings whose usage depends on the command involved. File names, 
where expected, are expanded via the normal shell conventions (see cj/z( 1) and sh( 1)). Special characters 
are recognized by certain commands and are documented with the commands below. 

STARTING MAIL 

At start-up time, mail reads commands from a system-wide file (/usr/lib/Mail.rc) to initialize certain 
parameters, then from a private start-up file ($HOME/.mailrc) for personalized variables. Most regular 
commands are legal inside start-up files, the most common use being to set up initial display options and 
alias lists. The following commands are not legal in the start-up file: !, Copy, edit, followup, Followup, 
hold, mail, preserve, reply, Reply, replyall, replysender, shell, and visual. Any errors in the start-up file 
cause the remaining lines in the file to be ignored. 

COMMANDS 

The following is a complete list of mail commands: 
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'.shell-command Escape to the shell. See ‘SHELL’ ( variables ). 

# comment Null command (comment). This may be useful in .mailrc files. 

= Print the current message number. 

? Prints a summary of commands. 

alias [alias name . . .] 
group [alias name . . .] 

Declare an alias for the given names. The names will be substituted when alias is used 
as a recipient. Useful in the .mailrc file. With no arguments, alias prints the current 
list of aliases. 

alternates name . . . Declares a list of alternate names for your login. When responding to a message, these 
names are removed from the list of recipients for the response. With no arguments, 
alternates prints the current list of alternate names. See also ‘allnet’ ( variables ). 

cd [ directory ] 

chdir [ directory ] Change directory. If directory is not specified, $home is used. 

copy [filename] 

copy [ms glist] filename 

Copy messages to the file without marking the messages as saved. Otherwise 
equivalent to the save command. 

Copy [mjgZwt] Save the specified messages in a file whose name is derived from the author of the 
message to be saved, without marking the messages as saved. Otherwise equivalent to 
the Save command. 

delete [ms glist] Delete messages from the mailbox. If ‘autoprint’ is set, the next message after the last 

one deleted is printed (see variables). 

discard [header-field ...] 
ignore [header-field . . .] 

Suppresses printing of the specified header fields when displaying messages on the 
screen. Examples of header fields to ignore are ‘status’ and ‘received’. The fields are 
included when the message is saved unless ‘alwaysignore’ is set (see variables). The 
Print and Type commands override any ignoring of header fields and display all 
header fields. 

dp [msglist] 

dt [msglist] Delete the specified messages from the mailbox and print the next message after the 

last one deleted. Roughly equivalent to a delete command followed by a print com- 
mand. 

echo string . . . Echo the given strings (like echo). 

edit [msglist] Edit the given messages. The messages are placed in a temporary file and the ‘EDI- 
TOR’ variable is used to get the name of the editor (see variables). Default editor is 
ex. 

exit 

x it Exit from mail, without changing the mailbox. No messages are saved in the mbox 

(see also quit). 

file [filename ] 

folder [filename ] Quit from the current file of messages and read in the specified file. Several special 

characters are recognized when used as file names, with the following substitutions: 


% 

the current mailbox. 

%user 

the mailbox for user. 

# 

the previous file. 

& 

the current mbox. 
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-i -folder the file folder in the folders directory. 

With no arguments, file prints the name of the current file and the number of messages 
and characters in that file. 

folders Print the names of the files in the directory set by the ‘folder’ variable (see variables). 

followup [ message ] 

Respond to a message, recording the response in a file whose name is derived from the 
author of the message. Overrides the ‘record’ variable, if set See also the Followup, 
Save, and Copy commands and ‘outfolder’ ( variables ). 

Followup [msglist] Respond to the first message in the msglist, sending the message to the author of each 
message in the msglist. The subject line is taken from the first message and the 
response is recorded in a file whose name is derived from the author of the first mes- 
sage. See also the followup. Save, and Copy commands and ‘outfolder’ ( variables ). 

from [msglist] Prints the header summary for the specified messages. 

group alias name . . . 

alias alias name . . . Declare an alias for the given names. The names will be substituted when alias is used 
as a recipient Useful in the .mailrc file. With no arguments, alias prints the current 
list of aliases. 

headers [ message ] Prints the page of headers which includes the message specified. The ‘screen’ variable 
sets the number of headers per page (see variables). See also the z command. 

help Prints a summary of commands. 

hold [msglist] 

preserve [msglist] Holds the specified messages in the mailbox, 
if s\r\t 

mail-commands 

else 

mail-commands 

endif Conditional execution, where s will execute following mail-commands, up to an else 

or endif, if the program is in send mode, r executes the mail-commands only in receive 
mode, and t executes the mail-commands only if mail is being run from a tty. Useful 
in the .mailrc file. 

ignore header-field . . . 
discard header-field . . . 

Suppress printing the specified header fields when displaying messages on the screen. 
Examples of header fields to ignore are ‘status’ and ‘received’. The fields are included 
when the message is saved unless ‘alwaysignore’ is set (see variables). The Print and 
Type commands override any ignoring of header fields and display all header fields. 

list Prints all commands available. No explanation is given, 

mail name . . . Mail a message to the specified users. 

mbox [msglist] Arrange for the given messages to end up in the standard mbox save file when mail ter- 
minates normally. See ‘mbox’ ( variables ) for a description of this file. See also the 
exit and quit commands. 

next [message] Go to next message matching message. A msglist may be specified, but in this case 
the first valid message in the list is the only one used. This is useful for jumping to the 
next message from a specific user, since the name would be taken as a command in the 
absence of a real command. See the discussion of msglists above for a description of 
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possible message specifications. 

pipe [msglist] [ shell-command ] 

| [msglist] [ shell-command '] 

Pipe the message through the given shell-command. The message is treated as if it 
were read. If no arguments are given, the current message is piped through the com- 
mand specified by the value of the ‘cmd’ variable. If the ‘page’ variable is set, a form 
feed character is inserted after each message (see variables). 

preserve [msglist] 
hold [ msglist ] 

Print [msglist] 

Type [ffwgfi'st] 

print [msglist] 
type [msglist] 


quit 

Reply [message] 

Respond [message] 

replyall [ message ] Reply to the specified message, including all other recipients of the message. If 
‘record’ is set to a filename, the response is saved at the end of that file (see vari- 
ables). If the ‘replyall’ variable is set, the actions of Reply/ Respond and reply/ 
respond are reversed. The replyall command always has the action described above; 
it is not affected by the ‘replyall’ variable. 

reply [msglist] 
respond [wiyg/z'sf] 
replysender [msglist] 

Send a response to the author of each message in the msglist. The subject line is taken 
from the first message. If ‘record’ is set to a filename, the response is saved at the end 
of that file (see variables). If the ‘replyall’ variable is set, the actions of Reply/ 
Respond and reply/ respond are reversed. The replysender command always has the 
action described above; it is not affected by the ‘replyall’ variable. 

Save [msglist] Save the specified messages in a file whose name is derived from the author of the first 
message. The name of the file is taken to be the author’s name with all network 
addressing stripped off. See also the Copy, followup, and Followup commands and 
‘outfolder’ ( variables ). 

save [filename] 
save [msglist] filename 

Save the specified messages in the given file. The file is created if it does not exist. 
The message is deleted from the mailbox when mail terminates unless ‘keepsave’ is 
set (see also variables and the exit and quit commands). Default file is the user’s 
mbox. 

set 

set name 
set name=string 

set name=number Define a variable called name. The variable may be given a null, string, or numeric 
value. Set by itself prints all defined variables and their values. See variables for 


Preserve the specified messages in the mailbox. 

Print the specified messages on the screen, including all header fields. Overrides 
suppression of fields by the ignore command. 

Print the specified messages. If ‘crt’ is set, the messages longer than the number of 
lines specified by the ‘crt’ variable are paged through the command specified by the 
‘ pager ’ variable. The default command is more (see variables). 

Exit from mail, storing messages that were read in mbox and unread messages in the 
mailbox. Messages that have been explicitly saved in a file are deleted. 
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shell 

size [msglist] 
source filename 
top [msglist] 

touch [msglist] 

Type [tfwg/wf] 
Print [msglist] 

type [tfiyg/isf] 
print [msglist] 


undelete [msglist] 


unset name . . . 

version 

visual [msg/isr] 


detailed descriptions of the mail variables. 

Invoke an interactive shell (see also ‘shell’ (variables)). 

Print the size in characters of the specified messages. 

Read commands from the given file and return to command mode. 

Print the top few lines of the specified messages. If the ‘toplines’ variable is set, it is 
taken as the number of lines to print (see variables). The default is 5. 

Touch the specified messages. If any message in msglist is not specifically saved in a 
file, it will be placed in the mbox upon normal termination. See exit and quit 

Print the specified messages on the screen, including all header fields. Overrides 
suppression of fields by the ignore command. 

Print the specified messages. If ‘crt’ is set, the messages longer than the number of 
lines specified by the ‘crt’ variable are paged through the command specified by the 
‘PAGER’ variable. The default command is more (see VARIABLES). 

Restore the specified deleted messages. Will only restore messages deleted in the 
current mail session. If ‘autoprint’ is set, the last message of those restored is printed 
(see VARIABLES). 

Erases the specified variables. If the variable was imported from the execution 
environment (that is, a shell variable) then it cannot be erased. 

Prints the current version and release date. 

Edit the given messages with a screen editor. The messages are placed in a temporary 
file and the ‘visual’ variable is used to get the name of the editor (see variables). 
Default screen editor is vi. 


write [msglist] filename 

Write the given messages on the specified file, minus the header and trailing blank 
line. Otherwise equivalent to the save command. 

xit 

ex *t Exit from mail, without changing the mailbox. No messages are saved in the mbox 

(see also quit). 

Z t+H Scroll the header display forward or backward one screen-full. The number of 

headers displayed is set by the ‘screen’ variable (see variables). 

TILDE ESCAPES 

The following commands may be entered only from input mode, by beginning a line with the tilde escape 
character ( ). See ‘escape’ ( variables ) for changing this special character. The tilde escape character may 
be entered as text by typing it twice (for example, typing 

" is the tilde escape character 
enters the line 


' is the tilde escape character 
into the message). 

'! shell-command Escape to the shell. 

Simulate end of file (terminate message input). 

mail-command 

mail-command Perform the command-level request. Valid only when sending a message while read- 
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-? 

"A 


"a 

"b name . . . 
'c name . . . 
'd 
"e 

"f [ttwg/Lr] 


ing mail. 

Print a summary of tilde escapes. 

Insert the autograph string ‘Sign’ into the message (see variables). 

Insert the autograph string ‘sign’ into the message (see variables). 

Add the names to the blind carbon copy (Bcc) list. 

Add the names to the carbon copy (Cc) list. 

Read in the dead.letter file. See ‘dead’ ( variables ) for a description of this file. 

Invoke the editor on the partial message. See also ‘editor’ (variables). 

Forward the specified messages. The messages are inserted into the message, without 
alteration, as opposed to the “m command. Valid only when sending a message while 
reading mail. 


"h 

“i string 


"m [msglist] 

P 

q 


Prompt for Subject line and To, Cc, and Bcc lists. If the field is displayed with an ini- 
tial value, it may be edited as if you had just typed it. 

Insert the value of the named variable into the text of the message. For example, 'A is 
equivalent to ‘"i Sign.’ 

Insert the specified messages into the letter, shifting the new text to the right one tab 
stop. Valid only when sending a message while reading mail. 

Print the message being entered. 

Quit from input mode by simulating an interrupt. If the body of the message is not 
null, the partial message is saved in the dead.letter file. See ‘dead’ (variables) for a 
description of this file. 


"r filename 
~< filename 

< \shell-command Read in the specified file. If the argument begins with an exclamation point (!), the 
rest of the string is taken as an arbitrary shell command and is executed, with the stan- 
dard output inserted into the message. 

"s string ... Set the subject line to string. 

t name . . . Add the given names to the To list. 


v 

”w filename 

”| shell-command 
VARIABLES 


Invoke a preferred screen editor on the partial message. See also ‘visual’ (vari- 
ables). 

Write the partial message onto the given file, without the header. 

Exit as with 'q except the message is not saved in the dead.letter file. 

Pipe the body of the message through the given shell-command. If the shell-command 
returns a successful exit status, the output of the command replaces the message. 


The following are environment variables taken from the execution environment and are not alterable within 
mail. 


HOME=directory The user’s base of operations. 

M.PJLRC=filename 

The name of the start-up file. Default is $HOME/.mailrc. 

The following variables are internal mail variables. They may be imported from the execution environ- 
ment or set via the set command at any time. The unset command may be used to erase variables. Using 
the set command with a no prepended to the variable name has the same effect as using the unset com- 
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mand with the variable name. 

allnet All network names whose last component (login name) match are treated as identical. 

This causes the msglist message specifications to behave similarly. Default is 
noallnet. See also the alternates command and the ‘metoo’ variable. 


alwaysignore 

append 

askcc 

asksub 

autoprint 

bang 


Ignores header fields with ignore everywhere, not just during print or type. Affects 
the save, Save, copy, Copy, top, pipe, and write commands, and the "m and ~f tilde 
escapes. 

Upon termination, append messages to the end of the mbox file instead of prepending 
them. Default is noappend but append is set in the global start-up file (which can be 
suppressed with the -n command line option). 

Prompt for the Cc list after message is entered. Default is noaskcc. 

Prompt for subject if it is not specified on the command line with the -s option. 
Enabled by default. 

Enable automatic printing of messages after delete and undelete commands. Default 
is noautoprint. 

Enable the special-casing of exclamation points (!) in shell escape command lines as 
in vz. Default is nobang. 


cmd =shell-command 

Set the default command for the pipe command. No default value. 

con \=conversion Convert uucp addresses to the specified address style. The only valid conversion now 
is internet, which requires a mail delivery program conforming to the RFC822 stan- 
dard for electronic mail addressing. Conversion is disabled by default. See also 
‘sendmail’ and the -U command line option. 


CTt=number 

DEAI>=filename 

debug 

dot 


Pipe messages having more than number lines through the command specified by the 
value of the ‘pager’ variable ( more by default). Disabled by default 

The name of the file in which to save partial letters in case of untimely interrupt or 
delivery errors. Default is $HOME/dead.letter. 

Enable verbose diagnostics for debugging. Messages are not delivered. Default is 
nodebug. 

Take a period on a line by itself during input from a terminal as end-of-file. Default is 
nodot but dot is set in the global start-up file (which can be suppressed with the -n 
command line option). 


EDITOR =shell-command 

The command to run when the edit or "e command is used. Default is ex. 


escap e=c 
folder ^directory 


header 

hold 

ignore 

ignoreeof 


Substitute c for the ' escape character. 

The directory for saving standard mail files. User specified file names beginning with 
a plus (+) are expanded by preceding the filename with this directory name to obtain 
the real filename. If directory does not start with a slash (/), $HOME is prepended to 
it. There is no default for the ‘folder’ variable. See also ‘outfolder’ below. 

Enable printing of the header summary when entering mail. Enabled by default. 

Preserve all messages that are read in the mailbox instead of putting them in the stan- 
dard mbox save file. Default is nohold. 

Ignore interrupts while entering messages. Handy for noisy dial-up lines. Default is 
noignore. 

Ignore end-of-file during message input. Input must be terminated by a period (.) on a 
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line by itself or by the command. Default is noignoreeof. See also ‘dot’ above. 

kee P When the mailbox is empty, truncate it to zero length instead of removing it Disabled 

by default. 

keepsave Keep messages that have been saved in other files in the mailbox instead of deleting 

them. Default is nokeepsave. 

LISTER =shell-command 

The command (and options) to use when listing the contents of the ‘folder’ directory. 
The default is Is. 

MBOX=filename The name of the file to save messages which have been read. The xit command over- 
rides this function, as does saving the message explicitly in another file. Default is 
$HOME/mbox. 

met0 ° If your login appears as a recipient, do not delete it from the list. Default is nometoo. 

no When used as a prefix to a variable name, has the effect of unsetting the variable. 

onehop When responding to a message that was originally sent to several recipients, the other 

recipient addresses are normally forced to be relative to the originating author’s 
machine for the response. This flag disables alteration of the recipients’ addresses, 
improving efficiency in a network where all machines can send directly to all other 
machines (that is, one hop away). 

outfolder Locates the files used to record outgoing messages in the directory specified by the 

‘folder’ variable unless the pathname is absolute. Default is nooutfolder. See ‘folder’ 
above and the Save, Copy, followup, and Followup commands. 

P a 8 e Used with the pipe command to insert a form feed after each message sent through the 

pipe. Default is nopage. 

PAGER =shell-command 

The command to use as a filter for paginating output. This can also be used to specify 
the options to be used. Default is more. 

prompt=s/n'rtg Set the command mode prompt to string. Default is ‘& ’. 

Refrain from printing the opening message and version when entering mail. Default is 
noquiet. 

record=filename Record all outgoing mail in filename. Disabled by default See also ‘outfolder’ above, 
replyall Reverses the effect of the reply and Reply commands. 

save Enable saving of messages in the dead.letter file on interrupt or delivery error. See 

‘dead’ for a description of this file. Enabled by default. 

screen =number Sets the number of lines in a screen— full of headers for the headers command, 

sendmai \=shell-command 

Alternate command for delivering messages. Default is sendmail. 
sendwait Wait for background mailer to finish before returning. Default is nosendwait. 

SHELL =shell-command 

The name of a preferred command interpreter. Default is sh. Normally inherited from 
the environment. 

showto When displaying the header summary and the message is from you, print the 

recipient’s name instead of the author’s name. 

sign=string The variable inserted into the text of a message when the "a (autograph) command is 
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given. No default (see also 'i (tilde escapes)). 


Sign =string The variable inserted into the text of a message when the "A command is given. No 

default (see also “i (tilde escapes)). 

toplines=/iwm6er The number of lines of header to print with the top command. Default is 5. 
verbose Invoke sendmail with the -v flag. 


VISUAL =shell-command 

The name of a preferred screen editor. Default is vi. 


FILES 


SHOME/.mailrc 

$HOME/mbox 

/usr/spool/mail/* 

/usr/lib/Mail.help* 

/usr/lib/Mail.rc 

/tmp/R[emqsx]* 


personal start-up file 
secondary storage file 
post office directory 
help message files 
global start-up file 
temporary files 


SEE ALSO 

binmail(l), sendmail(8), mailaddr(7) biff(l), fmt(l), aliases(5), newaliases(8). 

Mail is found in lusr/ucblMail, as a link to lusrlucblma.il. If you wish to use the original (version 7) UNIX 
mail program, you can find it in /bin/mail. Its man page is named binmail( 1). 

BUGS 

Where shell-command is shown as valid, arguments are not always allowed. Experimentation is recom- 
mended. 


Internal variables imported from the execution environment cannot be unset 

The full internet addressing is not fully supported by mail. The new standards need some time to settle 
down. 
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NAME 

mailtool - window- and mouse-based interface for mail 
SYNOPSIS 

mailtool [ -x ] [ -i seconds ] 

DESCRIPTION 

mailtool is a standard tool provided with the SunView environment. 

mailtool manages your mail in much the same manner as mail, but provides a more convenient and power- 
ful user interface. Scrollable windows allow easy access to your mailbox and mail folders. Software "but- 
tons make the most frequently used commands readily available. Less used commands are accessable 
from menus and keyboard accelerators are provided for the more experienced user. The full editing capa- 
bilities of textedit( 1) and the SunView selection service are available for modifying and composing mail. 
In addition, the behavior of mailtool may be customized by setting parameters with defaultsedit{\). Users 
who are not familiar with the mail program should read mail(l) and Mail User’s Guide in the Beginner’s 
Guide to the Sun Workstation. For more information on mailtool, text editing, and use of the selection ser- 
vice see Windows and Window-Based Tools: Beginner’ s Guide. 

OPTIONS 

—x expert mode — don t ask for confirmation after potentially damaging mail commands - off by 
default 

— i seconds 

check for new mail every seconds seconds - default is 300 (5 minutes) 
mailtool also accepts all of the generic tool arguments discussed in suntools{ 1). 

SUB WINDOWS 

mailtool consists of four scrollable subwindows. From top to bottom they are: 

header a read-only text subwindow which lists the header information {From: and Subject: and so 

on) for mail messages in the current folder or system mailbox 

command a panel subwindow with software buttons corresponding to the most frequently used mail 
commands, and two text items for directory and file names 

message a text subwindow that allows reading and the editing of messages that you have received 

composition a text subwindow in which to compose and reply to messages (this subwindow appears only 
when composing or replying) 

COMMAND BUTTONS 

All buttons except next and undelete operate on the currently selected message. To select a message, make 
a selection anywhere on the line in the header subwindow corresponding to the desired message. This is 
accomplished by positioning the cursor anywhere on the line, and clicking the select mouse button (the 
leftmost one). 

The set of command buttons in the command panel is as follows, 
abort quit the tool without modifying your system mailbox 

cd change to the directory specified in the Directory: text field 

cancel abort the message being composed in the composition subwindow 

commit commit changes to your system mailbox 

compose open the composition subwindow to compose (or forward - see below) a message 

copy copy the selected message to the file or folder specified in the File: text field 

deliver send the message being composed in the composition subwindow 
delete delete the selected message 

done commit changes and close the tool 
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folder 

new mail 

next 

preserve 

print 

quit 

reply 

save 

show 

undelete 

.mailrc 


commit changes and switch to the file or folder specified in the File: text field 

commit changes and reread the system mailbox to see new mail 

show the next message in the message subwindow 

hold the selected message in the system mailbox after the next commit 

print the selected message on a hardcopy printer 

commit changes and quit the tool 

open the composition subwindow to reply to the selected message 

save the selected message in the file or folder specified in the File: text field 

show the selected message in the message subwindow 

undelete the most recently deleted message(s) - this may be used repeatedly 

source your '/.mailrc file and thereby aquire the current option settings 


COMMAND MENUS 

All buttons in the command panel have menus behind them. Depress the right mouse button over a com- 
mand button to see its menu. Variations on a button command or related commands in mailtool have been 
grouped on these menus. For example, the reply buttton has menu items that reply to all recipients of the 
original message, reply including the original message, and reply to all recipients including the message. 
The compose button has the function forward grouped with it. All menus have corresponding keyboard 
acclerators - i.e. you may hold down a key while clicking the left mouse button to achieve the same effect 
without popping-up the menu. Two keys are used: shift and CTRL. In general, if a command has an 
"inverse" function like reversed direction, the shift key is used, and CTRL is used to "strengthen" a com- 
mand or invoke a related function. When a menu has actions corresponding to all four combinations of 
shift and CTRL, the order of the menu items is as follows: 
simply clicking on the command button, 
holding shift while clicking on the button, 
holding CTRL while clicking on the button, 
holding both shift and CTRL when clicking on the button. 

With this organization of commands, the keyboard accelerators for these command menu items may be 
quickly learned. Simply browse the button menus to discover what additional commands are available. 

There are two special file menus in the command panel. The menu behind the folder button will show you 
all your folders. The menu behind the File: text field holds the most recently used file (and folder) names. 
Selecting a name from these menus replaces the contents of the File: item just as if you typed the name. 
This name is used for the save, copy, and folder commands. Folder names are of the form +folder and are 
relative to the directory specified by the mail’s folder variable. Filenames typed into the File: field are 
relative to the directory specified in the Directory: field. 

To switch to a folder, select it from one of the file menus or type directly into the File: text field, and press 
the folder button. To return to your system mailbox, use the new mail button. 


MAIL VARIABLES 


mailtool interprets several variables in addition to those of mail. All can be set in your .mailrc file by using 
defaultsedit(l). 

allowreversescan allows you to work through your mailbox in the reverse, as well as forward, directions. 

This will affect which message is next - if the sense of direction is reverse then the 
message displayed by next is actually the previous one. 

autoprint display the next message when the current message is deleted or saved 

bell number of times to ring the bell when new mail arrives 

cmdlines number of lines in command panel 

expert sets expert mode - no confirmations required (same as the -x flag) 
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list of files to initialize the File: menu, (e.g. "+mbox +trash”) 
specifies the maximum size of the File: menu 
number of times to flash the window or icon when new mail arrives 
number of lines in header subwindow 
interval in seconds to check for new mail (same as the -i flag) 
number of lines in mail message subwindow 

percent of the message subwindow to remain visible during a reply or compose 
the command to use when printing mail — the default is Ipr -p. 
name of trash bin (if set to "+trash", this may be accessed like any other folder) 

If the trash variable is set, all deleted messages will be moved to the trash bin. You can look at the trash 
bin as with any other folder by typing its name to the File: item and hitting the folder button. The trash bin 
is emptied when you hit done. 

In addition, you can make your .mailrc conditionally set mail variables depending on whether it is running 
in the tty environment or the window environment. The command if t tests if you are in the tty environ- 
ment. For example: 

ift 

else 

set autoprint 
cd 

endif 

will set the variable autoprint and change to your home directory when mail is started in the SunView 
environment. 

FILES 

/usr/spool/mail/* post office 
/ .mailrc file giving initial mail commands 

SEE ALSO 

binmail(l), defaultsedit{\), mail{\), suntools(l), textedit( 1) 
aliases (5), mailaddrfl), newaliases( 8), sendmail (8) 

Mail User’s Guide in the Beginner's Guide to the Sun Workstation, 

Windows and Window-Based Tools: Beginner’ s Guide 

BUGS 

If mail receives an error then mailtool may hang and you must kill it. 

New mail status is only approximate, therefore the presence of new mail is not always accurately reflected 
in the icon image and tool namestripe. 

If you press done and immediately interact with another window, a few interactions may be lost while 
mailtool is becoming iconic. 


filemenu 

filemenusize 

flash 

header lines 

interval 

maillines 

msgpercent 

printmail 

trash 
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NAME 

make - maintain, update, and regenerate groups of programs 
SYNOPSIS 

make [-f makefile ] [— p] [— i] [-k] [-s] [— r] [-n] [— b] [— e] [-m] [— t] [-d] [— q] [-S] [ name ... ] 

OPTIONS 

— f makefile 

Description file name, makefile is assumed to be the name of a description file. A file name of - 
denotes the standard input. The contents of makefile override the built-in rules if they are present. 

-p Print out the complete set of macro definitions and target descriptions. 

-i Ignore error codes returned by invoked commands. This mode is entered if the fake target name 
JGNORE appears in the description file. 

-k Abandon work on the current entry, but continue on other branches that do not depend on that 
entry. 

-s Silent mode. Do not print command lines before executing. This mode is also entered if the fake 
target name .SILENT appears in the description file. 

-r Do not use the built-in rules. 

-n No execute mode. Print commands, but do not execute them. Even lines beginning with an @ are 
printed. 

-b Compatibility mode for old makefiles, -b is on by default. 

-e Environment variables override assignments within makefiles. 

-t Touch the target files (bringing them up-to-date) rather than issue the usual commands. 

-d Debug mode. Print out detailed information on files and times examined. 

-q Question. The make command returns a zero or non-zero status code depending on whether the 
target file is or is not up-to-date. 

-S Undoes the effect of the -k option. 

SPECIAL TARGET NAMES 

.DEFAULT If a file must be made but there are no explicit commands or relevant built-in rules, the com- 
mands associated with the name .DEFAULT are used if it exists. 

.PRECIOUS Dependents of this target will not be removed when quit or interrupt are hit. 

•SILENT Same effect as the -s option. 

.IGNORE Same effect as the -i option. 

DESCRIPTION 

make executes commands in makefile to update one or more target names. Name is typically a program. If 
no -f option is present, makefile, Makefile, s.makefile, s.Makefile, SCCS/s.makefiIe, and 
SCCS/s.Makefile are tried in order. If makefile is -, the standard input is taken. More than one 
-f makefile argument pair may appear. 

make updates a target only if its dependents are newer than the target. All prerequisite files of a target are 
added recursively to the list of targets. Missing files are deemed to be out of date. 

Include Files 

Make has an include file capability. If the string include appears as the first seven letters of a line in a 
makefile and is followed by a space or a tab, the string following the word include is taken as a filename 
which the current invocation of make will read, include files can be nested to a depth of no more than 
about 16 . 
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Make Entries 

Other than include lines, comments, and macro definitions, a Makefile contains a sequence of entries that 
specify dependencies. The first line of an entry is a blank-separated, non-null list of targets, then a :, then a 
(possibly null) list of prerequisite files or dependencies. Text following a ; and all following lines that 
begin with a tab are shell commands to be executed to update the target. The first line that does not begin 
with a tab or # begins a new dependency or macro definition. Shell commands may be continued across 
lines with the <backslashxnew-line> sequence. Everything printed by make (except the initial tab) is 
passed directly to the shell as is. Thus, 

echo a\ 
b 

will produce 
ab 

exactly the same as the shell would. 

Comments 

Sharp (#) and new-line surround comments. 

Example 

The following makefile says that pgm depends on two files a.o and b.o, and that they in turn depend on 
their corresponding source files (a.c and b.c) and a common file incLh: 

pgm: a.o b.o 

cc a.o b.o -o pgm 

a. o: incl.h a.c 

cc -c a.c 

b. o: incl.h b.c 

cc -c b.c 

Executing Command Lines 

Command lines are executed one at a time, each by its own shell. The first one or two characters in a com- 
mand can be the following: -, @, or If @ is present, the command is not printed before it is exe- 
cuted. If - is present, make ignores an error. A line is printed when it is executed unless the -s option is 
present, or the entry .SILENT: is in makefile, or unless the initial character sequence contains a @. The -n 
option specifies printing without execution; however, if the command line has the string $(MAKE) in it, the 
line is always executed (see discussion of the MAKEFLAGS macro under Environment). The -t (touch) 
option updates the modified date of a file without executing any commands. 

Commands returning non-zero status normally terminate make. If the -i option is present, or the entry 
JGNORE: appears in makefile, or the initial character sequence of the command contains -. the error is 
ignored. If the -k option is present, work is abandoned on the current entry, but continues on other 
branches that do not depend on that entry. 

The -b option allows old makefiles (those written for the old version of make) to run without errors. The 
difference between the old version of make and this version is that this version requires all dependency 
lines to have a (possibly null or implicit) command associated with them. The previous version of make 
assumed, if no command was specified explicitly, that the command was null. The -b option is on by 
default. 

Interrupt and quit cause the target to be deleted unless the target is a dependent of the special name .PRE- 
CIOUS. 

Environment 

make reads the environment. All environment variables are assumed to be macro definitions and are pro- 
cessed as such. Environment variables are processed before any makefile and after the internal rules; thus, 
macro assignments in a makefile override environment variables. The -e option makes the environment 
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override the macro assignments in a makefile. 

make processes MAKEFLAGS environment variable as containing any legal input option (except -f, -p, 
and -d) defined for the command line. Further, upon invocation, make “invents” the variable if it is not in 
the environment, puts the current options into it, and passes it on to invocations of commands. Thus, 
MAKEFLAGS always contains the current input options. This proves very useful for “super-makes”. In 
fact, as noted above, when the -n option is used, die command $(MAKE) is executed anyway; hence, one 
can perform a make -n recursively on a whole software system to see what would have been executed. 
This is because the -n is put in MAKEFLAGS and passed to further invocations of $(MAKE). This is one 
way of debugging all of the makefiles for a software project without actually doing anything. 

For compatibility with the 4.2bsd make, the MFLAGS variable is set from the MAKEFLAGS variable by 
prepending a MFLAGS is not exported. 

Macros 

Entries of the form stringl = string2 are macro definitions. String2 is defined as all characters up to a com- 
ment character or an unescaped new-line. Subsequent appearances of $(stringl [:substl =[subst2]]) are 
replaced by string2. The parentheses are optional if a single character macro name is used and there is no 
substitute sequence. The optional :substl =subst2 is a substitute sequence. If it is specified, all non- 
overlapping occurrences of substl in the named macro are replaced by subst2. Strings (for the purposes of 
this type of substitution) are delimited by blanks, tabs, new-line characters, and beginnings of lines. An 
example of the use of the substitute sequence is shown under Libraries. 

Internal Macros 

There are five internally maintained macros which are useful for writing rules for building targets. 

$* The macro $* stands for the file name part of the current dependent with the suffix deleted. It is 
evaluated only for inference rules. 

$@ The $@ macro stands for the full target name of the current target. It is evaluated only for explicitly 
named dependencies. 

$< The $< macro is only evaluated for inference rules or the .DEFAULT rule. It is the module which is 
out-of-date with respect to the target (that is, the “manufactured” dependent file name). Thus, in the 
.c.o rule, the $< macro would evaluate to the .c file. An example for making optimized .0 files from 
•c files is: 


.c.o: 

cc -c -O $*.c 


or: 


.c.o: 

cc -c -0 $< 

$? The $? macro is evaluated when explicit rules from the makefile are evaluated. It is the list of prere- 
quisites that are out of date with respect to the target; essentially, those modules which must be 
rebuilt. 

$% The $% macro is only evaluated when the target is an archive library member of the form Iib(ffie.o). 
In this case, $@ evaluates to lib and $% evaluates to the library member, file.o. 

Four of the five macros can have alternative forms. When an upper case D or F is appended to any of the 
four macros, the meaning is changed to “directory part” for D and “file part” for F. Thus, $(@D) refers 
to the directory part of the string $@. If there is no directory part, J is generated. The only macro 
excluded from this alternative form is $?. 

Suffixes 


Certain names (for instance, those ending with . 0 ) have inferable prerequisites such as .c, .s, etc. If no 
update commands for such a file appear in makefile, and if an inferable prerequisite exists, that prerequisite 
is compiled to make the target In this case, make has inference rules which allow building files from other 
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files by examining the suffixes and determining an appropriate inference rule to use. Default inference 
rules exist for the following suffixes: 

.c .c' .f .f .F .F' .r s' .sh .sh' 

•C.o .c .0 .c .c .f.o .r.f .F.o .F.o .F.F .r.o .r'.o ,r'.r .s.o .s'.o 
.y.o .y'.o .l.o .l'.o .y.c .y'.c .l.c .c.a .c'.a .s'.a .h'.h 

To print out make ’ s internal rules, use the following command (note that this command only works with 
the Bourne Shell): 

$ make — fp — 2>/dev/nuIl </dev/null 

A tilde in the above rules refers to an SCCS file (see sccsfile{ 5)). 

If you are using the C Shell, use this command to print out make’s internal rules: 
tutorial (make -fp - </dev/null >/dev/tty) >&/dev/nulI 

A tilde in the above rules refers to an SCCS file (see ^ccs(l)). Thus, the rule .c".o would transform an SCCS 
C source file into an object file (.o). 

Because the s. of the SCCS files is a prefix, it is incompatible with make’s suffix point-of-view. Hence, the 
tilde is a way of changing any file reference into an SCCS file reference. 

The SCCS subdirectory scheme of the sees command is supported by make by looking for SCCSIs.file if it 
can’t find s.file. 

A rule with only one suffix (that is, .c:) is the definition of how to build x from xx. In effect, the other 
suffix is null. This is useful for building targets from only one source file (for example, shell procedures, 
simple C programs). 

Additional suffixes are given as the dependency list for .SUFFIXES. Order is significant; the first possible 
name for which both a file and a rule exist is inferred as a prerequisite. The default list is: 

> .SUFFIXES: .o .c .c‘ .f .f .F .F .r .r' .p .p' .y .y' .1 .1" , s .s' .sh .sh' .h .h' 

Here again, the above command for printing the internal rules will display the list of suffixes implemented 
on the current machine. Multiple suffix lists accumulate; .SUFFIXES: with no dependencies clears the list 
of suffixes. 

Inference Rules 

The first example can be done more briefly. 

pgm: a.o b.o 

cc a.o b.o -o pgm 
a.o b.o: incl.h 

This is because make has a set of internal rules for building files. The user may add rules to this list by 
simply putting them in the makefile. 

Certain macros are used by the default inference rules to permit the inclusion of optional matter in any 
resulting commands. For example, CFLAGS, LFLAGS, and YFLAGS are used for compiler options to cc, 
lex, and yacc, respectively. Again, the previous method for examining the current rules is recommended. 

The inference of prerequisites can be controlled. The rule to create a file with suffix .o from a file with 
suffix .c is specified as an entry with .c.o: as the target and no dependents. Shell commands associated 
with the target define the rule for making a .o file from a .c file. Any target that has no slashes in it and 
starts with a dot is identified as a rule and not a true target. 

Libraries 

If a target or dependency name contains parentheses, it is assumed to be an archive library, the string 
within parentheses referring to a member within the library. Thus lib(file.o) and $(LIB)(file.o) both refer to 
an archive library which contains fiIe.o. (This assumes the LIB macro has been previously defined.) The 
expression $(LIB)(filel.o fi!e2.o) is not legal. Rules pertaining to archive libraries have the form Jff.a 
where the XX is the suffix from which the archive member is to be made. An unfortunate byproduct of the 
current implementation requires the XX to be different from the suffix of the archive member. Thus, one 
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cannot have lib(file.o) depend upon file.o explicitly. The most common use of the archive interface fol- 
lows. Here, we assume the source files are all C type source: 

lib: lib(filel.o) lib(file2.o) lib(file3.o) 

@echo lib is now up-to-date 
.c.a: 

$(CC) -c $(CFLAGS) $< 
ar rv $@ $*.o 
rm -f $*.o 

In fact, the .c.a rule listed above is built into make and is unnecessary in this example. A more interesting, 
but more limited example of an archive library maintenance construction follows: 

lib: lib(filel.o) lib(file2.o) lib(file3.o) 

$(CC) -c $(CFLAGS) $(?:.o=.c) 
ar rv lib $? 

rm $? @echo lib is now up-to-date 

.c.a:; 

Here the substitution mode of the macro expansions is used. The $? list is defined to be the set of object 
file names (inside lib) whose C source files are out-of-date. The substitution mode translates the .o to .c. 
Unfortunately, one cannot as yet transform to .c"; however, this may become possible in the future. Note 
also, the disabling of the .c.a: rule, which would have created each object file, one by one. This particular 
construct speeds up archive library maintenance considerably. This type of construct becomes very 
cumbersome if the archive library contains a mix of assembly programs and C programs. 

FILES 

[Mmjakefile and s.[Mm]akefile and SCCS/s.[mM]akefile 
SEE ALSO 

cc(l), cd(l), lex(l), sh(l), yacc(l), sccss(l) in Commands Reference for the Sun Workstation. 

UNIX System Programmer Reference Manual. 

BUGS 

Some commands return non-zero status inappropriately; use -i to overcome the difficulty. File names with 
the characters = : @ will not work. 

Commands that are directly executed by the shell, notably cd, are ineffectual across new-lines in make. 
The syntax (lib(filel.o file2.o file3.o) is illegal. 

You cannot build Iib(file.o) from file.o. 

In fact, the current version of make does not support references to objects in libraries (using the libe(file.o) 
notation) at all. 

The macro $(a:.o=.c') does not work. 
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NAME 

man - print out manual pages; find manual information by keywords 
SYNOPSIS 

man [ - ] [ -t ] [ -P path ] [ section ] title . . . 
man — k keyword . . . 
man -f file ... 

DESCRIPTION 

Man displays information from the UNIX System manual pages. Man can be asked for one line descrip- 
tions of commands specified by name, or for all commands whose description contains any of a set of key- 
words. Man can also provide on-line access to the sections of the printed manual. 

Man’s standard behavior when neither the -k nor -f option is specified (see OPTIONS below) is to format a 
specified set of manual pages. In the absence of any specific options to the contrary, man looks for already 
formatted manuals in the lusrlmanlcatl directories and uses the information cached there. Otherwise, man 
must format the pages on the fly — in this case you get a message asking you to wait patiently. 

If section is omitted, man searches all sections of the manual, giving preference to commands over subrou- 
tines in system libraries, and prints the first section it finds, if any. 

If a section is specified, man looks in that section of the manual for the given titles. Section is an arabic 
section number (‘3’ for instance); the number may be followed by a single letter classifier (‘lg’, for 
instance, indicating a graphics program in Section 1). Finally, section can be one of the keywords ‘public’, 
‘local’, ‘old’, or ‘new’. 

If the standard output is a terminal, or if you use the - flag, man pipes its output through car(l) with the -s 
option to crush out useless blank lines, u/(l) to create proper underlines for different terminals, and through 
more( 1) to stop after each page on the screen. Type a space to continue, and a control-D to scroll 11 more 
lines when the output stops. 

OPTIONS 

-P path Use path as the starting pathname for the manual pages. Manual page sections must reside in 
pathlmml instead of in lusrlmanl man? 

— k keywords 

Display a one line synopsis of each manual section whose listing in the table of contents contains 
any of the keywords. 

— f filenames 

Attempt to locate manual sections related to those files, and display the table of contents lines for 
those sections. 

-t Use troff to format the specified section, assuming you have a suitable raster output device which 
can actually handle troff s output. 

FILES 

/usr/man/man?/* manual pages in nr off! troff source 

/usr/man/cat?/* formatted manual pages 

SEE ALSO 

more(l), ul(l), whereis(l), catman(8) 
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NAME 

mesg - permit or deny messages 

SYNOPSIS 

mesg [ n ] [ y ] 

DESCRIPTION 

Mesg with argument n forbids messages via write (l) by revoking non-user write permission on the user’s 
terminal. Mesg with argument y reinstates permission. All by itself, mesg reports the current state without 
changing it. 

FILES 

/dev/tty* 

SEE ALSO 

write(l), talk(l) 

DIAGNOSTICS 

Exit status is 0 if messages are receivable, 1 if not, 2 on error. 
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NAME 

mkdir - make a directory 

SYNOPSIS 

mkdir dirname . . . 

DESCRIPTION 

Mkdir creates directories. Standard entries, V, for the directory itself, and ‘.. 1 
automatically. 

The current umask( 2) setting determines the mode in which directories are 
modified after creation by using chmod{ 1). 

Mkdir requires write permission in the parent directory. 

SEE ALSO 

chmod(l), rmdir(l), rm(l) 


for its parent, are made 
created. Modes may be 
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NAME 

mkstr — create an error message file by massaging C source 
SYNOPSIS 

mkstr [ - ] messagefile prefix file . . . 

DESCRIPTION 

Mkstr creates files of error messages. You can use mkstr to make programs with large numbers of error 
diagnostics much smaller, and to reduce system overhead in running the program — as the error messages 
do not have to be constantly swapped in and out. 

Mkstr processes each of the specified files, placing a massaged version of the input file in a file whose name 
consists of the specified prefix and the original name. A typical example of using mkstr would be: 

mkstr pistrings xx *.c 

This command would cause all the error messages from the C source files in the current directory to be 
placed in the file pistrings and processed copies of the source for these files to be placed in files whose 
names are prefixed with xx. 

To process the error messages in the source to the message file, mkstr keys on the string ‘error(’” in the 
input stream. Each time it occurs, the C string starting at the is placed in the message file followed by a 
null character and a new-line character; the null character terminates the message so it can be easily used 
when retrieved, the new-line character makes it possible to sensibly cat the error message file to see its 
contents. The massaged copy of the input file then contains a Iseek pointer into the file which can be used 
to retrieve the message, that is: 

char efilnameQ = "/usr/lib/pi_strings"; 

int efil = -1 ; 

error(al, a2, a3, a4) 

{ 

char buf[256]; 

if (efil < 0) { 

efil = open(efilname, 0); 
if (efil < 0) { 

oops: 

perror(efilname); 

exit(l); 

} 

} 

if (lseek(efil, (long) al, 0) 1 1 read(efil, buf, 256) <= 0) 
goto oops; 

printf(buf, a2, a3, a4); 

} 

OPTIONS 

- Place error messages at the end of the specified message file for recompiling part of a large mkstr ’d 
program. 

SEE ALSO 

xstr(l) 
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NAME 

more, page - browse through a text file 
SYNOPSIS 

more [ -cdflsu ] [ -lines ] [ +linenumber ] [ +1 pattern ] [ name . . . ] 
page [ -cdflsu ] [ -lines ] [ +linenumber ] [ +1 pattern ] [ name . . . ] 

DESCRIPTION 

More is a filter which displays the contents of a text file one screenful at a time on a video terminal. It nor- 
mally pauses after each screenful, and prints ‘--More-’ at the bottom of the screen. More displays another 
line if you type a carriage-return; more displays another screenful if you type a space. 

If you use the page command instead of the more command, the screen is cleared before each screenful is 
displayed (but only if a full screenful is being displayed), and k-\ rather than k- 2 lines are displayed in 
each screenful, where k is the number of lines the terminal can display. 

More looks in the file lelcltermcap to determine terminal characteristics, and to determine the default win- 
dow size. On a terminal capable of displaying 24 lines, the default window size is 22 lines. 

More looks in the environment variable MORE to pre-set any flags desired. For example, if you prefer to 
view files using the -c mode of operation, the csh command "setenv MORE -c" or the sh command 
sequence "MORE= -c' ; export MORE" would cause all invocations of more , including invocations by 
programs such as man to use this mode. Normally, the user will place the command sequence which sets 
up the MORE environment variable in the .login or .profile file. 

If more is reading from a file, rather than a pipe, a percentage is displayed along with the -More- prompt. 
This gives the fraction of the file (in characters, not lines) that has been read so far. 

Other sequences which may be typed when more pauses, and their effects, are as follows (i is an optional 
integer argument, defaulting to 1) : 

i<space> 

display i more lines, (or another screenful if no argument is given) 

T> display 1 1 more lines (a “scroll’ ’). If i is given, the scroll size is set to i . 
d same as "D (control-D) 

i z same as typing a space except that i , if present, becomes the new window size. 
i s skip i lines and print a screenful of lines 
i f skip i screenfuls and print a screenful of lines 
q or Q Exit from more. 

= Display the current line number. 

v Start up the editor vi at the current line. 

h Help command; give a description of all the more commands. 

i/expr search for the i-th occurrence of the regular expression expr. If there are less than i occurrences 
of expr , and the input is a file (rather than a pipe), the position in the file remains unchanged. 
Otherwise, a screenful is displayed, starting two lines before the place where the expression was 
found, or the end of the pipe, whichever comes first. The user’s erase and kill characters may be 
used to edit the regular expression. Erasing back past the first column cancels the search com- 
mand. 

i n search for the i -th occurrence of the last regular expression entered. 

(single quote) Go to the point from which the last search started. If no search has been performed 
in the current file, this command goes back to the beginning of the file. 
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Icommand 

invoke a shell with command. The characters *%’ and *!’ in "command" are replaced with the 
current file name and the previous shell command respectively. If there is no current file name, 
is not expanded. The sequences "\%" and "V!" are replaced by "%" and "!" respectively. 

i :n skip to the i -th next file given in the command line (skips to last file if n doesn’t make sense) 

i :p skip to the i -th previous file given in the command line. If this command is given in the middle of 

printing out a file, more goes back to the beginning of the file. If i doesn’t make sense, more skips 
back to the first file. If more is not reading from a file, the bell is rung and nothing else happens. 

:f display the current file name and line number. 

:q or :Q exit from more (same as q or Q). 

(dot) repeat the previous command. 

The commands take effect immediately; it is not necessary to type a carriage return. Up to the time when 
the command character itself is given, the user may type the line kill character to cancel the numerical 
argument being formed. In addition, the user may type the erase character to redisplay the -More-(xx%) 
message. 

At any time when output is being sent to the terminal, the user can type the quit key (normally controM). 
More stops sending output, and displays the usual -More-- prompt. The user may then enter one of the 
above commands in the normal manner. Unfortunately, some output is lost when this is done, due to the 
fact that any characters waiting in the terminal’s output queue are flushed when the quit signal occurs. 

More sets the terminal to noecho mode so that the output can be continuous. Thus what you type does not 
show on your terminal, except for the / and ! commands. 

If the standard output is not a terminal, more acts just like cat, except that a header is printed before each 
file in a series. 

OPTIONS 

-lines Set the size of the window to lines lines long instead of the default 

-c Display each page by redrawing the screen instead of scrolling. This makes it easier to read text 
while more is writing. This option is ignored if the terminal does not have the ability to clear to 
the end of a line. 

-d Display the message ‘Hit space to continue, Rubout to abort’ at the end of each screenful. This is 
useful if more is being used as a filter in some setting, such as a class, where users are unsophisti- 
cated. 

-f Count logical rather than screen lines. That is, long lines are not folded. This option is recom- 
mended if nroff output is being piped through ul, since the latter may generate escape sequences. 
These escape sequences contain characters which would ordinarily occupy screen postions, but 
which do not print when they are sent to the terminal as part of an escape sequence. Thus more 
may think that lines are longer than they actually are, and fold lines erroneously. 

-1 Do not treat X (form feed) specially. If -l is not used, more pauses after any line that contains a 
X, as if the end of a screenful had been reached. Also, if a file begins with a form feed, the screen 
is cleared before the file is printed. 

-s Squeeze multiple blank lines from the output, and replace them with single blank lines. Especially 
helpful when viewing nroff output, this option maximizes the useful information present on the 
screen. 

-u Normally, more handles underlining such as produced by nroff in a manner appropriate to the par- 
ticular terminal: if the terminal can perform underlining or has a stand-out mode, more outputs 
appropriate escape sequences to enable underlining or stand-out mode for underlined information 
in the source file. The -u option suppresses this processing. 

+linenumber 
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Start up at linenumber. 

+lpattern 

Start up two lines before the line containing the regular expression pattern. 

EXAMPLES 

A sample usage of more in previewing nroff output would be 
nroff -ms +2 doc.n | more -s 

FILES 

/etc/termcap Terminal data base 

/usr/lib/more.helpHelp file 

SEE ALSO 

csh(l), man(l), script(l), sh(l), environ(5), termcap(5) 
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NAME 

mt - magnetic tape manipulating program 
SYNOPSIS 

mt [ -f tapename ] command [ count ] 

DESCRIPTION 

mt sends commands to a magnetic tape drive. If tapename is not specified, the environment variable TAPE 
is used; if TAPE does not exist, mt uses the device Idev/rmtl2. Note that tapename must reference a raw 
(not block) tape device. By default mt performs the requested operation once. Operations may be per- 
formed multiple times by specifying count. 

The available commands are listed below. Only as many characters as are required to uniquely identify a 
command need be specified. 

eof, weof 

Write count end-of-file marks at the current position on the tape, 
fsf Forward space count files, 
fsr Forward space count records, 
bsf Back space count files, 
bsr Back space count records. 

For the following commands, count is ignored; 
rewind Rewind the tape, 
offline, rewoffl 

Rewind the tape and place the tape unit off-line, 
status Print status information about the tape unit 
retension 

Wind the tape to the end of the reel and then rewind it, smoothing out the tape tension. 
( count is ignored.) 

erase Erase the entire tape. 

mt returns a 0 exit status when the operation(s) were successful, 1 if the command was unrecognized, and 2 
if an operation failed. 

FILES 

/dev/rmt* Raw magnetic tape interface 

/dev/rar* Raw Archive cartridge tape interface 

/dev/rst*Raw SCSI tape interface 
/dev/rxt* Raw Xylogics tape interface 

SEE ALSO 

mtio(4), dd(l), environ(5) 

BUGS 

Not all devices support all options. For example, ar(4s) and st(4s) currently do not support the fsr, bsf, or 
bsr options; but they are the only only ones that currently support the retension and rewind options. 
Nine-track tapes, in particular, do not support the retension option. 
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NAME 

mv - move or rename files 
SYNOPSIS 

mv [ — i ] [ — f ] [ — ] filename 1 filename2 
mv [ -i ] [ -f ] [ - ] directoryl directory2 
mv [ — i ] [ — f ] [ — ] filename . . . directory . . . directory 
DESCRIPTION 

mv moves files and directories around in the file system. A side effect of mv is to rename a file or direc- 
tory. The three major forms of mv are shown in the synopsis above. 

The first form of mv moves (changes the name of) filename! to filename2 . \ffilename2 already exists, it is 
removed before filename 1 is moved, \ffilename2 has a mode which forbids writing, mv prints the mode 
(see chmod( 2)) and reads the standard input to obtain a line; if the line begins with y, the move takes place 
otherwise mv exits. ’ 

The second form of mv moves (changes the name of) directoryl to directory2, ONLY if directory2 does not 
already exist — if it does, the third form applies. 

The third form of mv moves one or mor e files and directories, with their original names, into the last direc- 
tory in the list. 

mv refuses to move a file or directory onto itself. 

OPTIONS 

-i interactive mode: mv displays the name of the file or directory followed by a question mark when- 
ever a move would replace an existing file or directory. If you type a line starting with ’y’, mv 
moves the specified file or directory, otherwise mv does nothing with that file or directory. 

— f force, override any mode restrictions and the — i switch. The — f option also suppresses any warn- 

ing messages about modes which would potentially restrict overwriting. 

Interpret all the following arguments to mv as file names. This allows file names starting with 
minus. 

SEE ALSO 

cp(l), ln(l) 

BUGS 

If filename 1 andfilename2 are on different file systems, then mv must copy the file and delete the original. 
In this case the owner name becomes that of the copying process and any linking relationship with other 
files is lost. 

mv will not move a directory from one file system to another. 
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NAME 

nice, nohup - run a command at low priority ( sh only) 

SYNOPSIS 

nice [ -number ] command [ arguments ] 
nohup command [ arguments ] 

DESCRIPTION 

Nice executes command with low scheduling priority. If the number argument is present, the priority is 
incremented (higher numbers mean lower priorities) by that amount up to a limit of 20. The default 
number is 10. 

The super-user may run commands with priority higher than normal by using a negative priority, e.g. 
‘— 10 ’. 

Nohup executes command immune to hangup and terminate signals from the controlling terminal. The 
priority is incremented by 5. Nohup should be invoked from the shell with *&’ in order to prevent it from 
responding to interrupts by or stealing the input from the next person who logs in on the same terminal. 
The syntax of nice is also different. 

FILES 

nohup.out standard output and standard error file under nohup 
SEE ALSO 

csh(l), nice(3C), renice(8) 

DIAGNOSTICS 

Nice returns the exit status of the subject command. 

BUGS 

Nice and nohup are particular to s/i(l). If you use csh(l), then commands executed with “&” are 
automatically immune to hangup signals while in the background. There is a builtin command nohup 
which provides immunity from terminate, but it does not redirect output to nohup.out. 

Nice is built into c^(l) with a slightly different syntax than described here. The form “nice +10” nices to 
positive nice, and “nice -10” can be used by the super-user to give a process more of the processor. 
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NAME 

nm - print name list 
SYNOPSIS 

nm [ -gnoprua ] [file...] 

DESCRIPTION 

Nm prints the name list (symbol table) of each object file in the argument list If an argument is an archive 
a listing for each object file in the archive will be produced. If no file is given, the symbols in a out are 
listed. 

Each symbol name is preceded by its value (blanks if undefined) and one of the letters: 

U undefined 

A absolute 

T text segment symbol 

D data segment symbol 

B bss segment symbol 

C common symbol 

f file name, 

debug, giving symbol table entries (see -a below). 

If the symbol is local (non-external) the type letter is in lower case. The output is sorted alphabetically. 
OPTIONS 

-g Print only global (external) symbols. 

-n Sort numerically rather than alphabetically. 

-o Prepend file or archive element name to each output line rather than only once. 

-p Don’t sort; print in symbol-table order. 

— r Sort in reverse order. 

— u Print only undefined symbols. 

-a Print all symbols. 

EXAMPLE 

nm 

prints the symbol list of a. out, the default output file for the C, FORTRAN 77 and Pascal compilers. 

SEE ALSO 

ar(l), ar(5), a.out(5) 
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NAME 

nroff - text formatting 
SYNOPSIS 

nroff [ -o pagelist ] [ -n N ] [ -s N ] [ -m name ] [ -raN ] [ -i ] [ -q ] [ -T name ] 

[ -e ] [ -fa ] [filename ] . . . 

DESCRIPTION 

nroff formats text in the named files for typewriter-like devices. See also troff{\). The full capabilities of 
nroff and troff are described in Formatting Documents with Nroff and Troff. 

If no file argument is present, nroff reads the standard input. An argument consisting of a single minus (-) 
is taken to be a file name corresponding to the standard input. 

OPTIONS 

Options may appear in any order so long as they appear before the files. 

-o list Print only pages whose page numbers appear in the comma-separated list of numbers and ranges. 

A range N-M means pages N through M ; an initial -N means from the beginning to page N ; and a 
final N- means from N to the end. 

-niV Number first generated page N . 

-s N Stop every N pages, nroff will halt prior to every N pages (default JV=1) to allow paper loading or 

changing, and will resume upon receipt of a newline. 

— m name 

Prepend the macro file lusrllibltmacltmac.name to the input files. 

-raN Set register a (one-character) to N. 

-i Read standard input after the input files are exhausted. 

-q Invoke the simultaneous input-output mode of the rd request. 

— T name 

Prepare output for a device of the specified name . Known names are: 


37 Teletype Corporation Model 37 terminal — this is the default 
tn300 GE TermiNet 300 (or any terminal without half-line capability). 
300 DASI-300. 

300-12 DASI-300 — 12-pitch. 

300S DASI-300S (or 302). 

300S-12 DASI-300S (or 302-12). 

300X DASI-300X. 

382 DASI-382 (fancy DTC 382). 

382-12 DASI-82 (fancy DTC 382 — 12-pitch). 

450 DASI-450 (Diablo Hyterm). 

450-12 DASI-450 (Diablo Hyterm) — 12-pitch. 

450-12-8 DASI-450 (Diablo Hyterm) — 12-pitch and 8 lines-per-inch. 
450X DASI-450X (Diablo Hyterm). 

833 AJ 833 or AJ 832. 

833-12 AJ 833 or AJ 832 — 12-pitch, 
itoh C:ITOH Prowriter. 


itoh- 12 C:ITOH Prowriter — 12-pitch. 

nec NEC 55?0 or NEC 77?0 Spinwriter. 

nec 12 NEC 5570 or NEC 7770 Spinwriter — 12-pitch. 

nec-t NEC 5570/7770 Spinwriter — Tech-Math/Times-Roman thimble. 

qume Qume Sprint — 5 or 9. 

qumel2 Qume Sprint — 5 or 9, 12-pitch. 

xerox Xerox 1770 or Diablo 1670. 
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xerox 12 Xerox 17?0 or Diablo 16?0 — 12-pitch, 
x-ecs Xerox/Diablo 1730/630 — Extended Character Set. 

x-ecsl2 Xerox/Diablo 1730/630 — Extended Character Set, 12-pitch, 
lpr Line printer. 

-e Produce equally-spaced words in adjusted lines, using full terminal resolution. 

-h Use output tabs during horizontal spacing to speed output and reduce output character count. Tab 

settings are assumed to be every 8 nominal character widths. 

EXAMPLE 

gaia% nroff — s4 —me users.guide 

Formats users.guide using the -me macro package, and stopping every 4 pages. 

FILES 

/tmp/ta* temporary file 

/usr/lib/ tmac/tmac. * standard macro files 
/usr/lib/term/* terminal driving tables for nroff 

/usr/lib/term/READMEindex to terminal description files 
SEE ALSO 

Formatting Documents on the Sun Workstation 

Using nroff and trof f on the Sun Workstation 

troff(l), eqn(l), tbl(l), ms(7), me(7), man(7), col(l), checknr(l) 
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NAME 

od - octal, decimal, hex, ascii dump 
SYNOPSIS 

od [ -format ] [ file ] [ [+]offset[.][b] [label] ] 

DESCRIPTION 

Od displays file, or it’s standard input, in one or more dump formats as selected by the first argument. If 
the first argument is missing, -o (octal) is the default. Dumping continues until end-of-file. 

The meanings of the format argument characters are: 

a Interpret bytes as characters and display them with their ASCII names. If the p character is given 
also, bytes with even parity are underlined. If the P character is given, bytes with odd parity are 
underlined. Otherwise the parity bit is ignored. 

b Interpret bytes as unsigned octal. 

c Interpret bytes as ASCII characters. Certain non-graphic characters appear as C escapes: null=\0, 
backspace=\b, formfeed=\f, newline=\n, retum=\r, tab=\t; others appear as 3-digit octal numbers. 
Bytes with the parity bit set are displayed in octal. 

d Interpret (short) words as unsigned decimal, 
f Interpret long words as floating point, 
h Interpret (short) words as unsigned hexadecimal, 
i Interpret (short) words as signed decimal. 

1 Interpret long words as signed decimal, 
o Interpret (short) words as unsigned octal. 

s[n] Look for strings of ASCII graphic characters, terminated with a null byte. N specifies the minimum 
length string to be recognized. By default, the minimum length is 3 characters. 

v Show all data. By default, display lines that are identical to the last line shown are not output, but are 
indicated with an in column 1. 

w[n] Specifies the number of input bytes to be interpreted and displayed on each output line. If w is not 
specified, 16 bytes are read for each display line. If n is not specified, it defaults to 32. 

x Interpret (short) words as hexadecimal. 

An upper case format character implies the long or double precision form of the object 

The offset argument specifies the byte offset into the file where dumping is to commence. By default this 
argument is interpreted in octal. A different radix can be specified; If is appended to the argument, 
then offset is interpreted in decimal. If offset begins with “x” or “Ox”, it is interpreted in hexadecimal. If 
“b” (“B”) is appended, the offset is interpreted as a block count, where a block is 512 (1024) bytes. If 
the file argument is omitted, an offset argument must be preceded by “+”. 

The radix of the displayed address will be the same as the radix of the offset, if specified; otherwise it will 
be octal. 

Label will be interpreted as a pseudo-address for the first byte displayed. It will be shown in “()” follow- 
ing the file offset. It is intended to be used with core images to indicate the real memory address. The syn- 
tax for label is identical to that for offset. 

SEE ALSO 

adb(l), dbxtool(l), dbx(l) 

BUGS 

A file name argument can’t start with “+”. A hexadecimal offset can’t be a block count. Only one file 
name argument can be given. 


224 Last change: 8 March 1984 Sun Release 3.0 



0D( 1 ) 


USER COMMANDS 


OD(l ) 


It is an historical botch to require specification of object, radix, and sign representation in a single character 
argument 
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NAME 

overview - run a program from SunView that takes over the screen 
SYNOPSIS 

overview [ generic tool Jlags ] programjiame [ arguments ] . . . 

DESCRIPTION 

Bitmap graphics based programs that are not SunView based can be run from SunView using overview. 
Overview shows an icon in SunView when overview is brought up iconic (-Wi flag) or when the program 
being run by overview is suspended (for example using ctrl-Z). Opening the overview icon, or starting 
overview non-iconic, starts the program named on the command line. Overview supresses SunView so that 
SunView window applications won’t interfere with the program’s display output or input devices. 

Overview is mainly designed to ran programs that fit the following profile: 

own display 

The program needs to own the bits on the screen. It doesn’t use the sunwindow or suntool 
libraries to arbitrate the use of the display and input devices between processes. 

keyboard input from stdin 

The program takes keyboard input from stdin directly. 

mouse input from Idevlmouse 

The program takes locator input from the mouse directly. 

SEE ALSO 

Windows and Window-Based Tools: Beginner’s Guide 
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NAME 

passwd — change login password 
SYNOPSIS 

passwd [ — f filename ] [ username ] 

DESCRIPTION 

This command changes (or installs) a password associated with the username (your own by default). 

passwd prompts for the old password and then for the new one. You must supply both, and the new pass- 
word must be typed twice to forestall mistakes. 

New passwords should be at least five characters long, if they combine upper and lower-case characters, or 
at least six characters long if in monocase. Users that persist in entering shorter passwords are compromis- 
ing their own security. 

Only the owner of the name or the super-user may change a password; the owner must prove he knows the 
old password. 

Use yppasswd to change your password in the network yellow pages. This will not affect your local pass- 
word, or your password on any remote machines on which you have accounts. 

OPTIONS 

-f Treat file as the password file. 

FILES 

/etc/passwd 

/etc/yp/passwd 

SEE ALSO 

login(l), passwd(5), yppasswd(l) 

Robert Morris and Ken Thompson, UNIX Password Security 

BUGS 

passwd will change a local password, but not a password in the network Yellow Pages. Refer to 
yppasswd (1) for information on how to change a Yellow Pages password. 
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NAME 

pc — Pascal compiler 
SYNOPSIS 

pc [ — c ] [ — g ] [ — o output ] [ — O ] [ — b ] [ — C ] [ -Dname[=def] ] \_float_option ] [ — H ] 

[ — i name . . . ] [ — I dir ] [ — 1 ] [ — lpfc ] [ — L ] [ — p ] [ — P ] [ — pg ] [ — s ] [ — S ] 

[ -U name ] [ -w ] [ -z ] [ -l]filename.p . . . 

DESCRIPTION 

Pc is the Sun Pascal compiler. If given an argument file ending with .p, pc compiles the file and leaves the 
result in an executable file called a. out by default. 

A program may be separated into more than one .p file. Pc will compile a number of .p files into object 
files (with the extension .o in place of .p). Object files may then be loaded into an executable a. out file. 
Exactly one object file must supply a program statement to successfully create an executable a. out file. 
The rest of the files must consist only of declarations which logically nest within the program. References 
to objects shared between separately compiled files are allowed if the objects are declared in included 
header files, whose names must end with .h. Header files may only be included at the outermost level, and 
thus declare only globally available objects. To allow external functions and procedures to be declared, 
an external directive has been added, whose use is similar to the forward directive but restricted to appear 
only in .h files. Function and procedure bodies may not appear in .h files. A binding phase of the com- 
piler checks that declarations are used consistently, to enforce the type checking rules of Pascal. 

Object files created by other language processors may be loaded together with object files created by pc. 
The functions and procedures they define must have been declared in .h files included by all the .p files 
which call those routines. 

Pascal’s calling conventions are compatible with those of C, with var parameters passed by address and 
other parameters passed by value. 

pc supports ISO Level 1 Standard Pascal, including conformant array parameters. Deviations from the ISO 
Standard are noted under BUGS below. 

See the Pascal User' s Manual for details. 

OPTIONS 

See ld(l) for load- time options. 

— c Suppress loading and produce .o file(s) from source file(s). 

-g Produce additional symbol table information for the symbolic debugger dbx( 1). 

-o name 

Name the final output file name instead of a.out. 

-O Optimize the object code. 

-b Buffer the file output in units of disk blocks, rather than lines 

— C Compile code to perform subscript and subrange checks and verify assert statements. Note that 

pointers are not checked. This option differs significantly from the -C option of the cc compiler. 

— D name[=def] 

Define name to the preprocessor, as if by a #define directive. If no def is given, name is defined 
as 1. 

float_option 

Floating-point code generation option. Can be one of: 

-fsoft software floating-point calls (This is the default). 

-fsky in-line code for Sky floating-point processor (supported only on Sun-2). 

-f6888I in-line code for Motorola 6888 1 floating-point processor supported only on Sun-3), 
-fswitch run-time-switched floating-point calls. The compiled object code is linked at run- 
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time to routines that support one of the above types of floating-point code. This was 
the default in previous releases. Only for use with programs that are floating-point 
intensive, and which must be portable to machines with various floating-point 
options. 

When invoked without floatation, the compiler interrogates the FLOATOPTION environment 
variable to determine the type of floating-point code to generate. Legal values for 
FLOATOPTION are: ‘fsoft’, ‘fsky’, ‘f68881’ and ‘fswitch’. 

-H Compile code to perform range checking on pointers into the heap. 

-i name Produce a listing for the specified procedures, functions and include files. 

-Idz'r Add dir to the list of directories in which to search for #include files with names not beginning 
with slash The preprocessor first searches for #include in the directory containing filename. p, 
then in directories named with -I options (if any), and finally, in /usr/include . 

-1 Make a program listing during translation. 

-Ipfc Load common startup code for programs containing mixed Pascal and FORTRAN 77 object files. 
Such programs should also be loaded with the FORTRAN 77 libraries (see files below). 

-L Map upper case letters in keywords and identifiers to lower case. 

-p Prepare object files for profiling with gprof(l). 

-P Use partial evaluation semantics for the boolean operators and and or. For these operators only, 
left-to-right evaluation is guaranteed, and the second operand is evaluated only if necessary to 
determine the result. 

-pg Produce counting code in the manner of -p, but invoke a run-time recording mechanism that 
keeps more extensive statistics and produces a gmon.out at normal termination. An execution 
profile can then be generated using gprof{ 1). 

-s Accept standard Pascal only; nonstandard constructs and extensions cause warning diagnostics. 

-S Compile the named program, and leave the assembly language output on the corresponding file 
suffixed ‘.s’. No ‘.o’ is created. 


— U name 

Remove any initial definition of name. 

-w Suppress warning messages. 

-z Allow execution profiling with pxp(l) by generating statement counters, and arranging for the 
creation of the profile data file pmon.out when the resulting object is executed. 

-Z Initialize local variables to zero. 

Other arguments are taken to be loader option arguments or libraries of pc -compatible routines. Certain 
flags can also be controlled by comments within the program, as described in the Pascal User’s Manual in 
the Sun Pascal Manual. 


FILES 

file.p 

/lib/cpp 

/usr/lib/pcO 

/lib/fl 

/usr/lib/pc2 

/lib/c2 

/usr/lib/pc3 

/usr/lib/pc3.2strings 

/usr/lib/how_pc 

/usr/lib/libpc.a 


Pascal source files 
macro preprocessor 
compiler front end 
code generator 

inline expander of library calls 
peephole optimizer 

separate compilation consistency checker 
text of the error messages 
basic usage explanation 
intrinsic functions and I/O library 
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/usr/lib/libpfc.a 
/usr/lib/libF7 7 . a 
/usr/lib/libI77.a 
/usr/lib/libU77.a 
/usr/lib/libm.a 
/lib/libc.a 

SEE ALSO 

The Pascal User's Manual 
pi(l), pxp(l), pxref(l) 

DIAGNOSTICS 

For a basic explanation do 
tutorial% pc 

In the diagnostic output of the translator, lines containing syntax errors are listed with a flag indicating the 
point of error. Diagnostic messages indicate the action which the recovery mechanism took in order to be 
able to continue parsing. Some diagnostics indicate only that the input is ‘malformed.’ This occurs if the 
recovery can find no simple correction to make the input syntactically valid. 

Semantic error diagnostics indicate a line in the source text near the point of error. Some errors evoke 
more than one diagnostic to help pinpoint the error; the follow-up messages begin with an ellipsis 

The first character of each error message indicates its class: 

E Fatal error; no code will be generated, 

e Nonfatal error, 

w Warning - a potential problem, 

s Nonstandard Pascal construct warning. 

If a severe error occurs which inhibits further processing, the translator will give a diagnostic and then 
‘QUIT’. 

Names whose definitions conflict with library definitions draw a warning. The library definition will be 
replaced by the one supplied in the Pascal program. Note that this can have unpleasant side effects. 

BUGS 

The keyword packed is recognized but has no effect. The ISO standard requires packed and unpacked 
structures to be distinguished for portability reasons. 

Binary set operators are required to have operands with identical types; the ISO standard allows different 
types, as long as the underlying base types are compatible. 

The -z flag doesn’t work for separately compiled files. 

Because the -s option is usurped by the compiler, it is not possible to pass the strip option to the loader. 
Thus programs which are to be stripped, must be run through strip ( 1) after they are compiled. 


startup code for combined Pascal and FORTRAN programs 

FORTRAN intrinsics library 

FORTRAN I/O library 

FORTRAN <=>Unix interface library 

math library 

standard library, see intro ( 3) 
in the Sun Pascal Manual. 
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NAME 

perfmeter - meter display of system performance values 
SYNOPSIS 

perfmeter [ -s sampletime ] [ -h hourhandintv ] [ -m minutehandintv ] 

[ -M value minmax maxmax ] [ -v value ] [ hostname ] 

DESCRIPTION 

perfmeter starts a tool whose iconic form is a meter displaying a system performance value, and whose 
open form is a strip chart of that value. The default is for the meter to be updated with a sampletime of 2 
seconds, for the hour hand to represent an average over an interval of 20 seconds, for the minute hand to 
represent an average over 2 seconds, and for the value being displayed to be percent of cpu being utilized. 
These defaults can be modified with command line arguments, or dynamically after the tool has been 
started. If there is no hostname argument, then the data displayed will be for the local machine, otherwise 
for the machine named by hostname. In either case, the rstatd(8) daemon must be running on the machine 
for which statistics are being reported. The maximum scale value for the strip chart will automatically dou- 
ble or halve to accommodate increasing or decreasing values. The scale limits can be set with a command 
line option. 

OPTIONS 

-s sampletime 

Sets the sample time to sampletime seconds. 

-h hourhandintv 

Sets the hour hand interval to hourhandintv seconds. 

— m minutehandintv 

Sets the minute hand interval to minutehandintv seconds. 

-M value minmax maxmax 
— v value 

Sets the performance value to be monitored to one of: 
cpu percent of cpu being utilized 

pkts ethemet packets per second 

page paging activity in pages per second 
swap jobs swapped per second 
intr number of device interrupts per second 
disk disk traffic in transfers per second 
cntxt number of context switches per second 

load average number of jobs running on the server over the last minute 

colls collisions per second detected on the ethemet 
errs errors per second on receiving packets 

COMMANDS 

The value being displayed can be changed by clicking the tool with the rightmost mouse button, and then 
selecting the appropriate menu item. The other meter parameters can be modified by moving the mouse 
cursor into the tool (either open or closed), and typing: 

m decreases minutehandintv by one 

M increases minutehandintv by one 

h decreases hourhandintv by one 

H increases hourhandintv by one 
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1-9 Sets sampletime to a range from 1 to 9 seconds. 

FILES 

/etc/servers starts statistics server 

SEE ALSO 

perfmon(l), netstat(8), vmstat(8), suntools(l), rstatd(8) 
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NAME 

perfmon - graphical display of general system statistics 
SYNOPSIS 

perfmon [ statistic . . . ] 

DESCRIPTION 

Perfmon provides a graphical display of the system-wide performance statistics and updates them approxi- 
mately once a second. It should be executed from a graphics tool inside the SunWindows system. The 
time interval between updates can be adjusted by typing one of the following characters while the mouse is 
in the graphics subwindow: 

s increases the interval by 0.05 seconds (small s means get slower by a little). 

S increases the interval by one second (capital S means get Slower by a lot), 

f decreases the interval by 0.05 seconds (small/ means get /aster by a little). 

F decreases the interval by one second (capital F means get Faster by a lot). 

R resets the interval to the standard 1.05 seconds. 

In addition, typing: 

H, h or ? 

lists the characters that perfmon is listening for. 

Q or q causes perfmon to cease executing. 

If no statistic argument is given, perfmon displays all statistics. A tick is placed on the lines separating the 
graphs once every fifteen seconds (due to scheduling vagaries, these ticks may not be evenly spaced). 

Statistics 

user is the percentage of total CPU time spent in normal and low priority user processes. 

system is the percentage of total CPU time attributed to system calls and overhead. 

idle is the percentage of total CPU time spent idle. 

free is the amount of available real memory (in Kbytes). 

disk is the total number of disk transfers performed. 

interrupts 

is the total number of interrupts serviced, 
input is the total number of input packets received, 
output is the total number of output packets transmitted, 
collision 

is the total number of collisions between packets observed on the network. 


SEE ALSO 

netstat(8), perfmeter(l), suntools(l), vmstat(8) 

BUGS 

Perfmon should use rstatd. 
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NAME 

pi - Pascal interpreter code translator 
SYNOPSIS 

pS [ —to ] [ — 1 ] [ — L ] [ — n ] [ — o name ] [ — p ] [ — s ] [ — t ] [ — u ] [ — w ] [ — z ] 

[ -i name . . . ] name.p 

DESCRIPTION 

Pi translates the program in the file name.p leaving interpreter code in the file obj in the current directory. 
The interpreter code can be executed using px. Pix performs the functions of pi and px for Toad and go’ 
Pascal. 

Both pi and pc( 1) support ISO Level 1 Standard Pascal, including conformant array parameters. Deviations 
from the ISO Standard are noted under BUGS below. 

OPTIONS 

The following flags are interpreted by pi; the associated options can also be controlled in comments within 
the program; see the Pascal User’s Manual in the Sun Fortran and Pascal 
Manual for details. 

-b Buffer the file output in units of disk blocks, rather than lines. 

— i name 

Enable the listing for any specified procedures, functions, and include files. 

-1 Make a program listing during translation. 

-L Map all identifiers and keywords to lower case. 

-n Begin each listed include file on a new page with a banner line. 

— o name 

Name the final output file name instead of a.out. 

-p Suppress the post-mortem control flow backtrace if an error occurs; suppress statement limit count- 
ing. 

-s Accept standard Pascal only; non-standard constructs cause warning diagnostics. 

-t Suppress runtime tests of subrange variables and treat assert statements as comments. 

-u Card image mode; only the first 72 characters of input lines are used. 

-w Suppress warning diagnostics. 

-z Allow execution profiling with pxp by generating statement counters, and arranging for the creation 
of the profile data file pmon.out when the resulting object is executed. 

FILES 

file.p input file 

file.i include file(s) 

/usr/lib/pi3.*strings text of the error messages 

/usr/lib/how_pi* basic usage explanation 

obj interpreter code output 

SEE ALSO 

Sun Fortran and Pascal Manual 
pix(l), px(l), pxp(l), pxref(l) 

DIAGNOSTICS 

For a basic explanation do 
tutorials pi 

In the diagnostic output of the translator, lines containing syntax errors are listed with a flag indicating the 
point of error. Diagnostic messages indicate the action which the recovery mechanism took in order to be 
able to continue parsing. Some diagnostics indicate only that the input is ‘malformed.’ This occurs if the 
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recovery can find no simple correction to make the input syntactically valid. 

Semantic error diagnostics indicate a line in the source text near the point of error. Some errors evoke 
more than one diagnostic to help pinpoint the error; the follow-up messages begin with an ellipsis 

The first character of each error message indicates its class: 

E Fatal error; no code will be generated, 

e Non-fatal error, 

w Warning - a potential problem, 

s Non-standard Pascal construct warning. 

If a severe error occurs which inhibits further processing, the translator will give a diagnostic and then 
‘QUIT’. 

BUGS 

The keyword packed is recognized but has no effect. The ISO standard requires packed and unpacked 
structures to be distinguished for portability reasons. 

Binary set operators are required to have operands with identical types; the ISO standard allows different 
types, as long as the underlying base types are compatible. 

For clarity, semantic errors should be flagged at an appropriate place in the source text, and multiple 
instances of the ‘same’ semantic error should be summarized at the end of a procedure or function rather 
than evoking many diagnostics. 

When include files are present, diagnostics relating to the last procedure in one file may appear after the 
beginning of the listing of the next. 
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NAME 

pix - Pascal translator and interpreter 
SYNOPSIS 

pix [ options ] [ -i name ... ] name.p [ argument ... ] 

DESCRIPTION 

Pix is a ‘load and go’ version of Pascal which combines the functions of the translator pi and the interpreter 
px. Pix uses pi to translate the program in the file name.p and, if there were no fatal errors during transla- 
tion, calls px to execute the resulting interpretive code with the specified arguments. A temporary file is 
used for the object code; the file obj is neither created nor destroyed. 

Options are as described under pi(l). 

FILES 

/usr/ucb/pi Pascal translator 

/usr/ucb/px Pascal interpreter 

/tmp/pix* temporary 

/usr/lib/how_pix basic explanation 

SEE ALSO 

The Pascal User's Manual in the Pascal for the Sun Workstation Manual. 

pi(l)> px(l) 

DIAGNOSTICS 

For a basic explanation do 
tutorial% pix 
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NAME 

plot - graphics filters 
SYNOPSIS 

plot [ -T terminal ] 

DESCRIPTION 

These commands read plotting instructions (see plot (5)) from the standard input, and in general produce 
plotting instructions suitable for a particular terminal on the standard output 

If no terminal type is specified, the environment parameter TERM (see environ (5)) is used. Known termi- 
nals are: 

4014 Tektronix 4014 storage scope. 

450 DASI Hyterm 450 terminal (Diablo mechanism). 

300 DASI 300 or GSI terminal (Diablo mechanism). 

300S DASI 300s terminal (Diablo mechanism), 
sun or ver 

Versatec D1200A printer-plotter. The output is scan-converted and suitable input to Ipr -v. 

FILES 

/usr/bin/tek 

/usr/bin/t450 

/usr/bin/t300 

/usr/bin/t300s 

/usr/bin/vplot 

/usr/tmp/vplot nnnnnn 

SEE ALSO 

plot(3X), plot(5), graph(lg), lpr(l), rasterfile(5). 
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NAME 

pmerge - pascal file merger 

SYNOPSIS 

pmerge name.p . . . 

DESCRIPTION 

Pmerge assembles the named Pascal files into a single standard Pascal program. The resulting program is 
listed on the standard output. It is intended to be used to merge a collection of separately compiled 
modules so that they can be run through pi, or exported to other sites. 

FILES 

/usr/tmp/MG* default temporary files 

SEE ALSO 

pc(l), pi(l), 

Auxiliary documentation Pascal User’ s Manual in the Sun Fortran and Pascal Manual. 

BUGS 

Very minimal error checking is done, so incorrect programs will produce unpredictable results. Block 
comments should be placed after the keyword to which they refer or they are likely to end up in bizarre 
places. 
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NAME 

pr — prepare file(s) for printing, possibly in multiple columns 
SYNOPSIS 

Pr [“«][+«][ -h string ] [ -wn ] [ -f ] [ -In ] [ -t ] [ -s/t ] [ -m ] [filename ] . . . 

DESCRIPTION 

pr prepares one or more files ’s for printing. The output is separated into pages headed by a date, the name 
of the file or a specified header, and the page number, pr prints its standard input if there are no file argu- 
ments. Formfeed characters in the input files cause page breaks in the output, as expected. 

Inter-terminal messages via write are forbidden during a pr. 

OPTIONS 

Options apply to all following file’s but may be reset be tween /i/c’s: 

— n Produce n -column output. For example: 

Print of in 

the one three 

lines file columns. 

This option overrides the -t option (see below). 

+n Begin printing with page n . 

— h string 

Use string as a header for the page instead of the default header. 

-w« For purposes of multi-column output, take the width of the page to be n characters instead of the 
default 72. 

-f Use formfeeds instead of newlines to separate pages. A formfeed is assumed to use up two blank 
lines at the top of a page. Thus this option does not affect the effective page length. 

-In Take the length of the page to be n lines instead of the default 66. 

-t Do not print the 5-line header or the 5-line trailer normally supplied for each page. Formfeed 
characters are not generated when this option is used, even if the -f option .,as used. The -t 
option is intended for applications where the results should be directed to a file for further process- 
ing. 

-sc Separate columns by the single character c instead of by the appropriate amount of white space. 
A missing c is taken to be a tab. 

-m Print all file’s simultaneously, each in one column, for example: 


Print 

Print 

Print 

the 

the 

third 

lines 

lines 

file's 

of 

of 

lines 

file 

file 

go 

one. 

two. 

here. 


EXAMPLES 

Print a file called dreadnought on the printer — this is the simplest use of pr: 
tutorial% pr dreadnought | lpr 
tutorial% 

Produce three laminations of a file called ridings side by side in the output, with no headers or trailers, the 
results to appear in the file called Yorkshire : 

tutorial% pr -m -t ridings ridings ridings > Yorkshire 
tutorial% 
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FILES 

/dev/tty? to suspend messages. 

SEE ALSO 

cat(l), lpr(l) 

DIAGNOSTICS 

There are no diagnostics when pr is printing on a terminal. 

BUGS 

The options described above interact with each other in strange and as yet to be defined ways. 
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NAME 

printenv - print out the environment 

SYNOPSIS 

printenv [ name ] 

DESCRIPTION 

Printenv prints out the values of the variables in the environment. If a name is specified, only its value is 
printed. 

If a name is specified and it is not defined in the environment, printenv returns exit status 1, else it returns 
status 0. 

SEE ALSO 

sh(l), environ(5), csh(l) 
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NAME 

prmail - display waiting mail 

SYNOPSIS 

prmail [ user ... ] 

DESCRIPTION 

Prmail displays waiting mail for you, or the specified user s. The mail is not disturbed. 

FILES 

/usr/spool/mail/* waiting mail files 
SEE ALSO 

biff(l), mail(l), from(l), binmail(l) 
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NAME 

prof - display profile data 
SYNOPSIS 

prof [ — a ] [ — 1 ] [ — n ] [ — s ] [ — v [ -low [ —high ] ] ] [ — z ] [ object-file [ profile-file . . . ] ] 

DESCRIPTION 

Prof interprets the file produced by the monitor (3) subroutine. In the default case, the symbol table in the 
named object file ( object-file by default) is read and correlated with the profile file (profile-file by default). 
For each external symbol, the percentage of time spent executing between that symbol and the next is 
printed (in decreasing order), together with the number of times that routine was called and the number of 
milliseconds per call. If more than one profile file is specified, the output represents the sum of the profiles. 

To tally the number of calls to a routine, the program must be compiled with the -p option of cc,f77 or pc. 
This option also means that the profile file is produced automatically. 

Beware of quantization errors. 

OPTIONS 

-a Report all symbols rather than just external symbols. 

-1 Sort the output by symbol value. 

-n sort the output by number of calls. 

-s Produce a summary profile file in mon .sum. This is really only useful when more than one profile 
file is specified. 

-v [ -low [ -high ]] 

Suppress all printing and produce a graphic version of the profile on the standard output for 
display by the plot (IG) filters. When plotting, the numbers low and high, (by default 0 and 100), 
select a percentage of the profile to be plotted, with accordingly higher resolution. 

— z Print routines which have zero usage (as indicated by call counts and accumulated time). 

FILES 

mon.out for profile 

a.out for namelist 

mon.sum for summary profile 

SEE ALSO 

monitor(3), cc(l), plot(lG), gprof(l) 

BUGS 

Prof is confused by/77 which puts the entry points at the bottom of subroutines and functions. 
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NAME 

prs - print an SCCS file 
SYNOPSIS 

/usr/sccs/prs [ -d [ dataspec ] ] [ -r [ SID ] ] [ -e ] [ -I ] [ -a ] filename . . . 

DESCRIPTION 

prs prints, on the standard output, parts or all of an SCCS file (see sccsfile (5)) in a user supplied format If 
a directory is named, prs behaves as though each file in the directory were specified as a named file, except 
that non-sccs files (last component of the path name does not begin with s.), and unreadable files are 
silently ignored. If a name of - is given, the standard input is read, in which case each line is taken to be 
the name of an SCCS file or directory to be processed; non-sccs files and unreadable files are silently 
ignored. 

OPTIONS 

Options apply independently to each named file. 

-d [ dataspec ] 

Specifies the output data specification. The dataspec is a string consisting of SCCS file data key- 
words (see DATA KEYWORDS) interspersed with optional user supplied text. 

-r[SID] 

Specifies the SCCS /Dentification (SID) string of a delta for which information is desired. If no 
SID is specified, the SID of the most recently created delta is assumed. 

-e Requests information for all deltas created earlier than and including the delta designated via the 
-r option. 

-I Requests information for all deltas created later than and including the delta designated via the -r 
option. 

-a Requests printing of information for both removed, that is, delta type = R, (see rmdel{ 1)) and 
existing, that is, delta type = D, deltas. If the -a option is not specified, information for existing 
deltas only is provided. 

In the absence of the -d options, prs displays a default set of information consisting of: delta-type, release 
number and level number, date and time last changed, user-name of the person who changed the file, lines 
inserted, changed, and unchanged, the MR numbers, and the comments. 

DATA KEYWORDS 

Data keywords specify which parts of an SCCS file are to be retrieved and output. All parts of an SCCS file 
(see sccsfile ( 5)) have an associated data keyword. There is no limit on the number of times a data keyword 
may appear in a dataspec . 

The information printed by prs consists of: 1) the user supplied text; and 2) appropriate values (extracted 
from the SCCS file) substituted for the recognized data keywords in the order of appearance in the 
dataspec. The format of a data keyword value is either Simple (S), in which keyword substitution is direct, 
or Multi-line (M), in which keyword substitution is followed by a carriage return. 

User supplied text is any text other than recognized data keywords. A tab is specified by \t and carriage 
retum/new-line is specified by \n. 
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TABLE 1. SCCS Files Data Keywords 


Keyword Data Item 

File Section 

Value 

Format 

:Dt: 

Delta information 

Delta Table 

See below* 

S 

:DL: 

Delta line statistics 

tt 

:Li:/:Ixl:/:Lu: 

S 

:Li: 

Lines inserted by Delta 

n 

nnnnn 

s 

:Ld: 

Lines deleted by Delta 

it 

nnnnn 

s 

:Lu: 

Lines unchanged by Delta 

ii 

nnnnn 

s 

:DT: 

Delta type 

11 

D or R 

s 

:I: 

SCCS ED string (SID) 

it 

:R:.:L:.:B:.:S: 

s 

:R: 

Release number 

ii 

nnnn 

s 

:L: 

Level number 

it 

nnnn 

s 

:B: 

Branch number 

it 

nnnn 

s 

:S: 

Sequence number 

ii 

nnnn 

s 

:D: 

Date Delta created 

ii 

:Dy:/:Dm:/:Dd: 

s 

:Dy: 

Year Delta created 

tt 

nn 

s 

:Dm: 

Month Delta created 

it 

nn 

s 

:Dd: 

Day Delta created 

it 

nn 

s 

:T: 

Time Delta created 

it 

:Th:::Tm:::Ts: 

s 

:Th: 

Hour Delta created 

it 

nn 

s 

:Tm: 

Minutes Delta created 

it 

nn 

s 

:Ts: 

Seconds Delta created 

" 

nn 

s 

:P: 

Programmer who created Delta 

it 

lognameS 

:DS: 

Delta sequence number 

•i 

nnnn 

S 

:DP: 

Predecessor Delta seq-no. 

it 

nnnn 

S 

:DI: 

Seq-no. of deltas incl., 
excl., ignored 

it 

:Dn:/:Dx:/:Dg: 

S 

:Dn: 

Deltas included (seq #) 

it 

:DS: :DS: ... 

S 

:Dx: 

Deltas excluded (seq #) 

it 

:DS: :DS:... 

S 

:Dg: 

Deltas ignored (seq #) 

it 

:DS: :DS: ... 

s 

:MR: 

MR numbers for delta 

ii 

text 

M 

:C: 

Comments for delta 

it 

text 

M 

:UN: 

User names 

User Names text 

M 

:FL: 

Flag list 

Flags 

text 

M 

:Y: 

Module type flag 

tt 

text 

S 

:MF: 

MR validation flag 

n 

yes or no 

S 

:MP: 

MR validation pgm name 

ti 

text 

S 

:KF: 

Keyword error/waming flag 

it 

yes or no 

S 

:BF: 

Branch flag 

n 

yes or no 

S 

:J: 

Joint edit flag 

ti 

yes or no 

S 

:LK: 

Locked releases 

it 

:R:... 

S 

:Q: 

User defined keyword 

n 

text 

s 

:M: 

Module name 

ii 

text 

s 

:FB: 

Floor boundary 

it 

:R: 

s 

:CB: 

Ceiling boundary 

ti 

:R: 

s 

:Ds: 

Default SID 

ii 

• X* 

s 

:ND: 

Null delta flag 

it 

yes or no 

s 

:FD: 

File descriptive text 

Comments 

text 

M 

:BD: 

Body 

Body 

text 

M 

:GB: 

Gotten body 

ii 

text 

M 

:W: 

A form of what string 

N/A 

:Z::M:\t:I: 

s 

:A: 

A form of what string 

N/A 

:Z::Y: :M: :I::Z: 

s 

:Z: 

what string delimiter 

N/A 

@(#) 

s 

:F: 

SCCS file name 

N/A 

text 

s 

:PN: 

SCCS file path name N/A 

* :Dt: = :DT: :I: :D: :T: :P: :DS: :DP: 

text 

s 
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EXAMPLES 

/usr/sccs/prs -d"Users and/or user IDs for :F: are:\n:UN:" s.file 

may produce on the standard output: 

Users and/or user IDs for s.file are: 

xyz 

131 

abc 

/usr/sccs/prs -d"Newest delta for pgm :M:: :I: Created :D: By :P:" -r s.file 
may produce on the standard output: 

Newest delta for pgm main.c: 3.7 Created 77/12/1 By cas 
As a special case: 

/usr/sccs/prs s.file 
may produce on the standard output: 

D 1.1 77/12/1 00:00:00 cas 1 000000/00000/00000 
MRs: 

bl78-12345 

W79-54321 

COMMENTS: 

this is the comment line for s.file initial delta 

for each delta table entry of the “D” type. The only option argument allowed to be used with the special 
case is the -a option. 

FILES 

/tmp/pr????? 

SEE ALSO 

sccs(l), admin(l), delta(l), get(l), help(l), sccsfile(5) 

Source Code Control System in Programming Tools for the Sun Workstation. 

DIAGNOSTICS 

Use help for explanations. 
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NAME 

ps - process status 
SYNOPSIS 

ps [ acCegklsStuvwx ] [ num] [ kernel _name ] [ c_dump_file ] [ swapjle ] 

DESCRIPTION 

ps displays information about processes. Normally, only processes that you (your user-id) have started are 
candidates to be displayed by ps, but see the OPTIONS section below for how to get more information. 
Specifying a makes other users’ processes candidates to be displayed; specifying x includes processes 
without control terminals in the candidate pool. 

All output formats include, for each process, the process id — PID, control terminal of the process — TT, 
cpu time used by the process — TIME (this includes both user and system time), the state — STAT — of 
the process, and an indication of the COMMAND which is running. 

The state is given by a sequence of four letters, for example, ‘RWNA’. 

First letter indicates the runnability of the process: 

R Runnable processes, 

T Stopped processes, 

P Processes in page wait, 

D Processes in disk (or other short term) waits, 

S Processes sleeping for less than about 20 seconds, 

I Processes which are idle (sleeping longer than about 20 seconds). 

Z A child processes that has terminated and is waiting for its parent process to do a 
wait. 

Second letter indicates whether a process is swapped out; 
blank 

(that is, a space) in this position indicates that the process is loaded (in memory). 

W Process is swapped out 

> Process has specified a soft limit on memory requirements and has exceeded that 
limit; such a process is (necessarily) not swapped. 

Third letter indicates whether a process is running with altered CPU scheduling priority (nice): 
blank 

(that is, a space) in this position indicates that the process is running without special 
treatment. 

N The process priority is reduced, 

< The process priority has been raised artificially. 

F ourth letter indicates any special treatment of the process for virtual memory replacement. The 

letters correspond to options to the vadvise (2) system call. Currently the possibilities 
are: 
blank 

(that is, a space) in this position stands for VA_NORM. 

A Stands for VA_ANOM. An A typically represents a program which is doing gar- 
bage collection. 

S Stands for VA_SEQL. An S is typical of large image processing programs which 
are using virtual memory to sequentially address voluminous data. 

Kerneljiame specifies the location of the system namelist. If the k option is given, c_dump Jile tells ps 
where to look for core. Otherwise, the core dump is located in the file Ivmcore and this argument is 
ignored. Swap Jile gives the location of a swap file other than the default, Idevldrum . 

OPTIONS 

a Display information about all processes with terminals (ordinarily only one’s own processes are 
displayed). 
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c Display the command name, as stored internally in the system for purposes of accounting, rather than 
the command arguments, which are kept in the process’ address space. This is more reliable, if less 
informative, since the process is free to destroy the latter information. 

C Display raw CPU time in the %CPU field instead of the decaying average. 

e Display the environment as well as the arguments to the command. 

g Display all processes. Without this option, ps only prints ‘interesting’ processes. Processes are 
deemed to be uninteresting if they are process group leaders. This normally eliminates top-level 
command interpreters and processes waiting for users to login on free terminals. 

k Normally, kernel name, defaults to /vmunix, c_dump Jile is ignored, and swap Jle defaults to 
Idevldrum. With the k option in effect, these arguments default to Ivmunix, Ivmcore, and I dev/ drum, 
respectively. 

1 Display a long listing, with fields PPID, CP, PRI, NI, ADDR, SIZE, RSS and WCHAN as described 
below. 

s Adds the size SSIZ of the kernel stack of each process (for use by system maintained) to the basic 
output format. 

S Display accumulated CPU time used by this process and all of its reaped children. 

tx Restrict output to processes whose controlling tty is x (which should be specified as printed by ps, for 
example, t3 for tty3, tco for console, tdO for ttydO, t? for processes with no tty, etc). This option 
must be the last one given. 

u Display user-oriented output. This includes fields USER, %CPU, NICE, SIZE, and RSS as described 
below. 

v Display a version of the output containing virtual memory. This includes fields RE, SL, PAGEIN, 
SIZE, RSS, LIM, TSIZ, TRS, %CPU and %MEM, described below. 

w Use a wide output format (132 columns rather than 80); if repeated, that is, ww, use arbitrarily wide 
output. This information is used to decide how much of long commands to print. 

x Display even those processes with no terminal. 

num A process number may be given, in which case the output is restricted to that process. This option 
must also be last. 

DISPLAY FORMATS 

Fields which are not common to all output formats: 

USER name of the owner of the process 

%CPU cpu utilization of the process; this is a decaying average over up to a minute of previous (real) 
time. Since the time base over which this is computed varies (since processes may be very 
young) it is possible for the sum of all %CPU fields to exceed 100%. 

NICE (or NI) process scheduling increment (see setpriority{ 2) and nice{ 3C). 

SIZE virtual size of the process (in kilobyte units) 

RSS real memory (resident set) size of the process (in kilobyte units) 

LIM soft limit on memory used, specified via a call to getrlimit{ 2); if no limit has been specified 

then shown as xx 

TSIZ size of text (shared program) image 
TRS size of resident (real memory) set of text 

%MEM percentage of real memory used by this process. 

RE residency time of the process (seconds in core) 

SL sleep time of the process (seconds blocked) 

PAGEIN number of disk i/o’s resulting from references by the process to pages not loaded in core. 

UID numerical user-id of process owner 

PPID numerical id of parent of process 

CP short-term cpu utilization factor (used in scheduling) 
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PRI process priority (non-positive when in non-interruptible wait) 

ADDR page fram number or swap area position 

WCHAN event on which process is waiting (an address in the system), with the initial part of the address 
trimmed off, for example, 80004000 prints as 4000. 

F flags associated with process as in <sys/proc.h>: 

SLOAD 0000001 in core 

SSYS 0000002 swapper or pager process 

SLOCK 0000004 process being swapped out 
SSWAP 0000008 save area flag 

STRC 0000010 process is being traced 

SWTED 0000020 another tracing flag 

SULOCK 0000040 user settable lock in core 

SPAGE 0000080 process in page wait state 
SKEEP 0000100 another flag to prevent swap out 
SOMASK 0000200 restore old mask after taking signal 
SWEXIT 0000400 working on exiting 

SPHYSIO 0000800 doing physical i/o (bio.c) 

SVFORK 0001000 process resulted from vfork() 

SVFDONE 0002000 another vfork flag 

SNOVM 0004000 no vm, parent in a vfork() 

SPAGI 0008000 init data space on demand, from inode 
SSEQL 0010000 user warned of sequential vm behavior 
SUANOM 0020000 user warned of anomalous vm behavior 
STIMO 0040000 timing out during sleep 

SOUSIG 0100000 using old signal mechanism 

SOWEUPC 0200000 owe process an addupc() call at next ast 
SSEL 0400000 selecting; wakeup/waiting danger 

SLOGIN 0800000 a login process (legit child of init) 

SPTECHG 1000000 pte’s for process have changed 

A process that has exited and has a parent, but has not yet been waited for by the parent is marked 
<defunct>; a process which is blocked trying to exit is marked <exiting>; ps makes an educated guess as to 
the file name and arguments given when the process was created by examining memory or the swap area. 
The method is inherently somewhat unreliable and in any event a process is entitled to destroy this infor- 
mation, so the names cannot be counted on too much. 

FILES 

/vmunix system namelist 
/dev/kmem kernel memory 
/dev/drum swap device 
/vmcore core file 

/dev searched to find swap device and tty names 

SEE ALSO 

kill(l), w(l) 

BUGS 

Things can change while ps is running; the picture it gives is only a close approximation to reality. 
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NAME 

pti - phototypesetter interpreter 

SYNOPSIS 

pti [file ... ] 

DESCRIPTION 

Pti shows the commands in a stream from the standard output of troff{\) using trojfs -t option, interpret- 
ing them as they would act on the typesetter. Horizontal motions shows as counts in internal units and are 
marked with *<’ and V indicating left and right motion. Vertical space is called leading and is also indi- 
cated. 

The output is really cryptic unless you are an experienced C/A/T hardware person. It is better to use 
troff -a. 

SEE ALSO 

troff(l) 
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NAME 

ptx - permuted index 
SYNOPSIS 

ptx [-f] [ — t ] [-w/z] [-gn] [ -o only ] [ -i ignore ] [-b break] [-r ] [ input [ output ] ] 

DESCRIPTION 

Pbc generates a permuted index of the contents of file input onto file output (defaults are standard input and 
output). Ptx has three phases: the first does the permutation, generating one line for each keyword in an 
input line. The keyword is rotated to the front. The permuted file is then sorted. Finally, the sorted lines 
are rotated so the keyword comes at the middle of the page. Ptx produces output in the form: 

.xx "tail" "before keyword" "keyword and after" "head" 

where .xx may be an nr off (\) or troff{\) macro for user-defined formatting. The before keyword and key- 
word and after fields incorporate as much of the line as will fit around the keyword when it is printed at the 
middle of the page. Tail and head, at least one of which is an empty string "", are wrapped-around pieces 
small enough to fit in the unused space at the opposite end of the line. When original text must be dis- 
carded, 7’ marks the spot. 

OPTIONS 

-f Fold upper and lower case letters for sorting. 

-t Prepare the output for the phototypesetter; the default line length is 100 characters. 

— w« Use the next argument, n, as the width of the output line. The default line length is 72 characters. 

—gn Use the next argument, n, as the number of characters to allow for each gap among the four parts 

of the line as finally printed. The default gap is 3 characters. 

_ o only Use as keywords only the words given in the only file. 

-i ignore 

Do not use as keywords any words given in the ignore file. If the -i and -o options are missing, 
use lusr/lib/eign as the ignore file. 

-b break 

Use the characters in the break file to separate words. In any case, tab, newline, and space charac- 
ters are always used as break characters. 

— r Take any leading nonblank characters of each input line to be a reference identifier (as to a page 

or chapter) separate from the text of the line. Attach that identifier as a 5th field on each output 
line. 

FILES 

/bin/sort 

/usr/lib/eign 

BUGS 

Line length counts do not account for overstriking or proportional spacing. 
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NAME 

pwd - print working directory name 

SYNOPSIS 

pwd 

DESCRIPTION 

Pwd prints the pathname of the working (current) directory. 

If you are using csA(l), you can use the dirs builtin command to do the same job more quickly; BUT dirs 
can give a different answer in the rare case that the current directory or a containing directory was moved 
after the shell descended into it. This is because pwd searches back up the directory tree to report the true 
pathname, whereas dirs remembers the pathname from the last cd command. The example below illus- 
trates the differences. 

% cd /usr/wendy/january/reports 
% pwd 

/usr/wendy/j anuary/reports 
% dirs 

'/january/reports 
% mv Tjanuary '/february 
% pwd 

/usr/wendy/february/reports 
% dirs 

'/january/reports 

% 

Pwd and dirs also give different answers when you change directory through a symbolic link. For exam- 
ple: 

% cd /usr/wendy/january/reports 
% pwd 

/usr/wendy/j anuary/reports 
% dirs 

"/january/reports 
% Is -1 /usr/wendy/january 

lrwxrwxrwx 1 wendy 17 Jan 30 1983 /usr/wendy/january ->/usr/wendy/1984/jan/ 

% cd /usr/wendy/january 
% pwd 

/usr/wendy/1984/jan 
% dirs 

/usr/wendy/j anuary 

They may also report different pathnames if you have changed directories through a symbolic 
link. 

SEE ALSO 

cd(l), csh(l) 
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NAME 

px - Pascal interpreter 
SYNOPSIS 

px [ obj [ argument ... ] ] 


description 


FILES 


Px interprets the abstract machine code generated by pi. The first argument is the file to be interpreted and 
defaults to oby remaining arguments are available to the Pascal program using the built-ins argv and argc 
Px is also invoked by pix when running Toad and go’. 6 


If the program terminates abnormally an error message and a control flow backtrace are printed. The 
number of statements executed and total execution time are printed after normal termination. The p option 
°f P 1 su PP r esses all of this except the message indicating the cause of abnormal termination. 


obj default object file 

pmon.out profile data file 


SEE ALSO 

The P ascal User's Manual in the Sun Pascal Manual. 
pi(l)> pix(l) 


DIAGNOSTICS 

Most run-time error messages are self-explanatory. Some of the more unusual ones are: 

Reference to an inactive file 

A file other than input or output was used before a call to reset or rewrite. 

Statement count limit exceeded 

The limit of 500,000 executed statements (which prevents excessive looping or recursion) has been 
exceeded. 


Bad data found on integer read 
Bad data found on real read 

Usually, non-numeric input was found for a number. For reals, Pascal requires digits before and 
after the decimal point so that numbers like ‘.1’ or ‘21.’ evoke the second diagnostic, 
panic: Some message 

Indicates a internal inconsistency detected in px probably due to a Pascal system bug. 

BUGS 

Post-mortem traceback is not limited; infinite recursion leads to almost infinite traceback. 
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NAME 

pxp - Pascal execution profiler 
SYNOPSIS 

pxp [ -acdefjLnstuw_ ] [ -23456789 ] [ -z [ name ... ] ] name.p 
DESCRIPTION 

Pxp can be used to obtain execution profiles of Pascal programs or as a pretty-printer. To produce an exe- 
cution profile all that is necessary is to translate the program specifying the z option to pc, pi, or pix, exe- 
cute the program, and then type the command 
tutorial% pxp -z name.p 

Pxp generates a reformatted listing if none of the c, t, or z options are specified; thus 
tutorial% pxp old.p > new.p 

places a pretty-printed version of the program in old.p in the file new.p. 

OPTIONS 

The use of the following options of pxp is discussed in the Pascal User’s Manual in the Sun Pascal 
Manual. 

-a Print the bodies of all procedures and functions in the profile; even those which were never executed, 
-c Extract profile data from the file core . 

-d Include declaration parts in a profile. 

-e Eliminate include directives when reformatting a file; the include is replaced by the reformatted con- 
tents of the specified file. 

-f Fully parenthesize expressions. 

-j Left justify all procedures and functions. 

-L Map all identifiers and keywords to lower case. 

— n Eject a new page as each file is included; in profiles, print a blank line at the top of the page. 

-s Strip comments from the input text. 

-t Print a table summarizing procedure and function call counts. 

-u Card image mode; only the first 72 characters of input lines are used. 

-w Suppress warning diagnostics. 

— z Generate an execution profile. If no name s are given the profile is of the entire program. If a list of 

names is given, then only the specified procedures or functions and the contents of the specified 
include files will appear in the profile. 

Underline keywords. 

— d Use d spaces (where d is a digit, 2 < d < 9) as the basic indenting unit. The default is 4. 

FILES 

name.p input file 

name.i include file(s) 

name.h include file(s) 

pmon.out profile data 

core profile data source for -c option 

/usr/lib/how_pxp information on basic usage 
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SEE ALSO 

The Pascal User’s Manual in the Sun Pascal Manual. 
pc(l), pi(l), px(l) 

DIAGNOSTICS 

For a basic explanation do 
tutorial% pxp 

Error diagnostics include No profile data in file’ with the c option if the z option was not enabled to pi; 
‘Not a Pascal system core file’ if the core is not from a px execution; ‘Program and count data do not 
correspond’ if the program was changed after compilation, before profiling; or if the wrong program is 
specified. 

BUGS 

Does not place multiple statements per line. 

Procedures and functions as parameters are printed without nested parameter lists, as in the obsolete Jensen 
and Wirth syntax. 
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NAME 

pxref- Pascal cross-reference program 

SYNOPSIS 

pxref [ - ] name 

DESCRIPTION 

Pxref makes a line numbered listing and a cross-reference of identifier usage for the program in name. The 
optional ’ argument suppresses the listing. The keywords goto and label are treated as identifiers for the 
purpose of the cross-reference. Include directives are not processed, but cause the placement of an entry 
indexed by ‘#include’ in the cross-reference. 

SEE ALSO 

The Pascal User’s Manual in the Sun Fortran and Pascal Manual. 

BUGS 

Identifiers are trimmed to 10 characters. 
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NAME 

quota - display disk usage and limits 
SYNOPSIS 

quota [ -v ] [ user ] 

DESCRIPTION 

Quota displays users disk usage and limits. Only the super-user may use the optional user argument to 
view the limits of users other than himself. 

Quota without any flags prints only warnings about mounted file systems where usage is over quota. 

If a -v flag is supplied, quota will display user’s quotas on all mounted file systems where quotas exist. 

FILES 

quotas quota file at the file system root 

SEE ALSO 

quotactl(2), quotaon(8), edquota(8), rquotad(8c) 
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NAME 

ranlib - convert archives to random libraries 

SYNOPSIS 

ranlib archive . . . 

DESCRIPTION 

Ranlib converts each archive argument to a form which the linker W( 1) can load more rapidly. Ranlib 

does this by adding a table of contents called .SYMDEF to the beginning of the archive. Ranlib uses 

ar{\) to reconstruct the archive, so that sufficient temporary file space must be available in the file system 
which contains the current directory. 

SEE ALSO 

ld(l), ar(l), lorder(l) 

BUGS 

Because generation of a library by or and randomization of the library by ranlib are separate processes, 
phase errors are possible. The linker warns when the modification date of a library is more recent than the 
creation date of its dictionary; but this means that you get the warning even if you only copy the library. 


258 


Last change: 8 February 1983 


Sun Release 3.0 



RASTPS ( 1 ) 


USER COMMANDS 


RASTPS ( 1 ) 


NAME 

rastps — convert screen (raster file) image to PostScript 
SYNOPSIS 

rastps [ -atf ] [ -htf ] [-p] [-rtf] [-s] [-Wtf ] [-xtf] [ -yN] filename ... 

DESCRIPTION 

rastps converts screen images and rasterfiles to PostScript form. The image can then be printed a 
PostScript printer such as the Sun LaserWriter. 

A sample use might be 

% rastps -w3 my_raster | Ipr 

where my_raster is a raster file (that could have been produced by screendump{ 1)). 

A common use is 

% screendump | rastps | Ipr 

to produce an image the Workstation screen image on a LaserWriter. It takes about 4 minutes to print a 
non-rotated screendump. If rotation is requested, the time needed increases to about 30 minutes. 

OPTIONS 

-aN Adjusts the image to a printer with resolution of N dots per inch. When N is omitted, the resolution 
is set to 300. 

-hN Set height of the printed image in inches. 

-p Portrait mode. 

—rtf Rotate the figure by tf. 

-s Select standard pixels. Normally produces (square) rasterfile pixels. 

-wtf Set width of the printed image in inches. 

-xtf Specify in inches the location of the lower left-hand comer of the image on the page. 

-y tf Specify in inches the location of the upper right-hand comer of the image. 
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NAME 

rastrepl - magnify a raster image by 2 times 
SYNOPSIS 

rastrepl [ input-file [ output-file ]] 

DESCRIPTION 

Rastrepl reads input-file (or the standard input if input-file is not specified) which should be in rasterfile for- 
mat (see /usr/include/rasterfile.h), replicates each pixel in both the x and y directions, and writes the result- 
ing rasterfile to output-file (or the standard output if output-file is not specified). 

EXAMPLES 

tutorial^, screendump | rastrepl | lpr -Pversatec -v 

sends a rasterfile containing the current frame buffer to the Versatec plotter, doubling the size of the image 
so that it fills a single page. 

SEE ALSO 

screendump(l), screenload(l), lpr(l) 
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NAME 

ratfor - rational FORTRAN dialect 
SYNOPSIS 

ratfor [ -6 c ] [ -C ] [ -h ] [ filename . . . ] 

DESCRIPTION 

ratfor converts the rational FORTRAN dialect into ordinary FORTRAN 77. It provides control flow con- 
structs essentially identical to those in C. See the fortran 77 Programmer' s Guide for a description of the 
Ratfor language. 

OPTIONS 

—6c Use the character c as the continuation character in column 6 when translating to FORTRAN. The 
default is to use the & character as a continuation character. 

-C Pass Ratfor comments through to the translated code. 

h Translate Ratfor string constants to Hollerith constants of the form nnnh string. Otherwise just 
pass the strings through to the translated code. 

SEE ALSO 

f77(l) 

Ratfor in the FORTRAN 77 Programmer’ s Guide 
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NAME 

rep - remote file copy 

SYNOPSIS 

rep filel file2 

rep [ -r ] file ... directory 

DESCRIPTION 

rep copies files between machines. Each file or directory argument is either a remote file name of the form 
“rhost:path”, or a local file name (containing no *:’ characters, or a 7’ before any ‘:’s.) 

If the -r is specified and any of the source files are directories, rep copies each subtree rooted at that name; 
in this case the destination must be a directory. 

If path is not a full path name, it is interpreted relative to your login directory on rhost. A path on a remote 
host may be quoted (using \, ", or ') so that the metacharacters are interpreted remotely. 

rep does not prompt for passwords; your current local user name must exist on rhost and allow remote 
command execution via rs/i(lC). 

rep handles third party copies, where neither source nor target files are on the current machine. Hostnames 
may also take the form “rhostmame” to use rname rather than the current user name on the remote host. 

Please note: rep is meant to copy from one host to another; if by some chance you try to copy a file on top 
of itself, you will end up with a severely corrupted file (for example, if you executed the following com- 
mand from host george: ‘george% rep testfile george:/usr/me/testfile’). Remember where you are at all 
times (putting your hostname in your prompt helps with this)! 

SEE ALSO 

ftp(lC), rsh(lC), rlogin(lC) 

BUGS 

Doesn’t detect all cases where the target of a copy might be a file in cases where only a directory should be 
legal. 

Is confused by any output generated by commands in a .login, .profile, or .eshre file on the remote host. 
rep doesn’t copy ownership, mode, and timestamps to the new files. 

rep requires that the source host have permission to execute commands on the remote host when doing 
third-party copies. 

If you forget to quote metacharacters intended for the remote host you get an incomprehesible error mes- 
sage. 
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NAME 

refer - find and insert literature references in documents 
SYNOPSIS 

refer [ -ar ] [ -b ] [ -c string ] [ -e ] [ -kx ] [ -1 m,n ] [ -pfile ] [ -n ] [ -s keys ] file . . . 

DESCRIPTION 

Refer is a preprocessor for nroff( 1), or trojf(l), that finds and formats references. The input files (standard 
input by default) are copied to the standard output, except for lines between .[ and .] command lines. Such 
lines are assumed to contain keywords as for lookbib(l), and are replaced by information from a biblio- 
graphic data base. The user can avoid the search, override fields from it, or add new fields. The reference 
data, from whatever source, is assigned to a set of troff strings. Macro packages such as ms(l) print the 
finished reference text from these strings. A flag is placed in the text at the point of reference. By default, 
the references are indicated by numbers. 

When refer is used with eqn{ 1), neqn(Y), or tbl( 1), refer should be used first in the sequence, to minimize 
the volume of data passed through pipes. 

OPTIONS 

-ar Reverse the first r author names (Jones, J. A. instead of J. A. Jones). If r is omitted, all author 
names are reversed. 

-b Bare mode — do not put any flags in text (neither numbers or labels). 

—cstring 

Capitalize (with Small Caps) the fields whose key-letters are in string. 

-e Accumulate references instead of leaving the references where encountered, until a sequence of 
the form: 

•[ 

$LIST$ 

.] 

is encountered, and then write out all references collected so far. Collapse references to the same 
source. 

-kx Instead of numbering references, use labels as specified in a reference data line beginning with the 
characters %x; By default, x is L. 

-]m,n Instead of numbering references, use labels from the senior author’s last name and the year of 
publication. Only the first m letters of the last name and the last n digits of the date are used. If 
either of m or n is omitted, the entire name or date, respectively, is used. 

-p Take the next argument as a file of references to be searched. The default file is searched last. 

-n Do not search the default file. 

-skeys Sort references by fields whose key-letters are in the keys string, and permute reference numbers 
in the text accordingly. Using this option implies the -e option. The key-letters in keys may be 
followed by a number indicating how many such fields are used, with a + sign taken as a very 
large number. The default is AD, which sorts on the senior author and date. To sort on all authors 
and then the date, for instance, use the options -sA+T. 

FILES 

/usr/dict/papers directory of default publication lists and indexes 
/usr/lib/refer directory of programs 

SEE ALSO 

addbib(l), indxbib(l), lookbib(l), roffbib(l), sortbib(l) 
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NAME 

rev - reverse lines of a file 

SYNOPSIS 

rev [ file ] ... 

DESCRIPTION 

Rev copies the named files to the standard output, reversing the order of characters in every line. If no file 
is specified, the standard input is copied. 
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NAME 

rlogin - remote login 
SYNOPSIS 

rlogin rhost [ -ec ] [ -1 username ] [ -7 ] [ -8 ] 
rhost [ -ec ] [ -I username ] [ -7 ] [ -8 ] 

DESCRIPTION 

rlogin connects your terminal on the current local host system Ihost to the remote host system rhost. 

Host names are given in the file /etc/hosts. Each host has one standard name (the first name given in the 
file), which is unambiguous, and optionally one or more nicknames. The host names for machines to 
which your machine is networked are also found in the directory /usr/hosts, as symbolic links to rsh. If you 
put this directory in your search path then the rlogin can be omitted. 

Additionally, each host has a file letclhosts.equiv which contains a list of rhost ’ s with which it shares 
account names. When you rlogin on a host specified in your letclhosts.equiv (and if the remote host, in 
turn, specifies your host in its /etc/ hosts. equiv) you don’t need to give a password. 

Each user may also have a private equivalence list in a file .rhosts in his login directory. Each line in this 
file should contain an rhost and a username separated by a space, giving additional cases where logins 
without passwords are to be permitted. If the originating user and host is not found in these files, the 
remote machine will prompt for a password. 

To avoid some security problems, the .rhosts file must be owned by either the remote user or root and may 
not be a symbolic link. 

Your remote terminal type is the same as your local terminal type (as given in your environment TERM 
variable). All echoing takes place at the remote site, so that (except for delays) the rlogin is transparent. 
Flow control via A S and A Q and flushing of input and output on interrupts are handled properly. 

ESCAPES 

Lines that you type which start with the tilde character are ‘escape sequences’ (the escape character can be 
changed via the -e options): 

Disconnect from the remote host — this is not the same as a logout, because the local host breaks 
the connection with no warning to the remote end. 

"susp Suspend the login session (only if you are using the C-Shell). susp is your ‘suspend’ character — 
usually A Z — see «y(l). 

dsusp Suspend the input half of the login, but output will still be seen (only if you are using the C-Shell). 
dsusp is your ‘deferred suspend’ character — usually A Y — see tty(l). 

OPTIONS 

-1 Specifies a different user name ( username , in the synopsis) for the remote login. If you do not use 
this option, the remote username used is the same as your local username. 

-e Specifies a different escape character (c , in the synopsis) for the line used to disconnect from the 
remote host. 

-8 Pass eight-bit data across the net instead of seven-bit data. 

SEE ALSO 

rsh(lC), stty(l) 

FILES 

/usr/hosts/* 

/etc/hosts.equiv 
"/.rhosts 

BUGS 


for rhost version of the command 

list of rhost s with shared account names 

private list of rhost s with shared account names 
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This implementation can only use the TCP network service. 
More terminal characteristics should be propagated. 
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NAME 

rm - remove (unlink) files or directories 
SYNOPSIS 

rm ( — f ] [ — r ] [ — i ] [ — ] file . . . 

DESCRIPTION 

rm removes (directory entries for) one or more files. If an entry was the last link to the file, the contents of 
that file are lost. See ln(l) for more information about links. 

To remove a file, you must have write permission in its directory; but you don’t need read or write permis- 
sion on the file itself. If you don’t have write permission on the file and the standard input is a terminal, rm 
displays the file s permissions and waits for you to type in a response. If your response begins with ‘y’ the 
file is deleted; otherwise the file is left alone. 

rm -r and rmdir remove entries for directories, rmdir removes the named directory only if it is empty To 
remove a directory containing files, use rm with the -r option. See rmdir (l) for more information about 
removing directories. 

OPTIONS 

— f Force files to be removed, without displaying permissions, asking questions, or reporting errors. 

-r Recursively delete the contents of the specified directory (and its subdirectories), and the directory 

itself. 

i Ask whether to delete each file, or, under — r, whether to examine each directory. Sometimes 
called the interactive option. 

Treat the following arguments as filenames — so that you can specify filenames starting with a 
minus. 

WARNING 

It is forbidden to remove the file *..’ merely to avoid the antisocial consequences of inadvertently doing 
something like ‘rm — r .*’. 

SEE ALSO 

rmdir(l), ln(l) 
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NAME 

rmdel - remove a delta from an SCCS file 
SYNOPSIS 

/usr/sccs/rmdel -rSID file . . . 

DESCRIPTION 

Rmdel removes the delta specified by the SID from each named SCCS file. The delta to be removed must be 
the newest (most recent) delta in its branch in the delta chain of each named SCCS file. In addition, the SID 
specified must not be that of a version being edited for the purpose of making a delta (that is, if a p-file (see 
get{ 1)) exists for the named SCCS file, the SID specified must not appear in any entry of the p-file). 

If a directory is named, rmdel behaves as though each file in the directory were specified as a named file, 
except that non-SCCS files (last component of the path name does not begin with s.) and unreadable files 
are silently ignored. If a name of - is given, the standard input is read; each line of the standard input is 
taken to be the name of an SCCS file to be processed; non-SCCS files and unreadable files are silently 
ignored. 

The exact permissions necessary to remove a delta are documented in the Source Code Control System 
User’s Guide. Simply stated, they are either 1) if you make a delta you can remove it; or 2) if you own the 
file and directory you can remove a delta. 

FILES 

x-file (see delta( 1)) 

z-file (see delta{ 1)) 

SEE ALSO 

sccs(l), delta(l), get(l), help(l), prs(l), sccsfile(5). 

Source Code Control System in Programming Tools for the Sun Workstation. 

DIAGNOSTICS 

Use help(l) for explanations. 
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NAME 

rmdir, rm -r - remove (unlink) directories or files 
SYNOPSIS 

rmdir dir ... 

rm — r [ — f ] [ — i ] [ — ] filename . . . 

DESCRIPTION 

rmdir removes the named directories, which must be empty. 

rm, with the -r option, recursively removes directories, subdirectories, and any files they contain. See 
m(l) for more information. If the -i (interactive) option is in effect, rm asks whether to delete each file, 
and whether to examine each directory. 

The null option, -, indicates that all following arguments are filenames. This allow you to specify filenames 
starting with a minus to rm. 

SEE ALSO 

rm(l) 
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NAME 

roffbib - run off bibliographic database 
SYNOPSIS 

roffbib [ -e ] [ -h ] [ -m name ] [ -n p ] [ -olist ] [ -Q ] [ -raN ] [ -sN ] [ -Tterm ] [ -V ] 

[ -x ] [ filename ] ... 

DESCRIPTION 

Roffbib prints out all records in a bibliographic database, in bibliography format rather than as footnotes or 
endnotes. Generally it is used in conjunction with sortbib: 

sortbib database | roffbib 


OPTIONS 

Roffbib accepts all options understood by nr off (l) except -i and -q. 

-e Produce equally-spaced words in adjusted lines using full terminal resolution. 

-h Use output tabs during horizontal spacing to speed output and reduce output character count. Tab 
settings are assumed to be every 8 nominal character widths. 

— m Prepend the macro file lusr/lib/tmacltmac.name to the input files. There should be a space 

between the -m and the macro filename. This set of macros will replace the ones defined in 
/usr/lib/tmac/tmac.bib. 

-up Number first generated page p . 

-olist Print only page numbers that appear in the comma-separated list of numbers and ranges. A range 
N-M means pages N through M; an initial -N means from the beginning to page N; a final N- 
means from page N to end. 

-Q Queue output for the phototypesetter. Page offset is set to 1 inch. 

-raN Set register a (one-character) to N. The command-line argument -rNl will number the refer- 

ences starting at 1. 

Four command-line registers control formatting style of the bibliography, much like the number 
registers of ms( 7). The flag -rV2 will double space the bibliography, while -rVl will double 
space references but single space annotation paragraphs. The line length can be changed from the 
default 6.5 inches to 6 inches with the -rL6i argument, and the page offset can be set from the 
default of 0 to one inch by specifying -rOli (capital O, not zero). 

— s N Halt prior to every N pages for paper loading or changing (default N =1). To resume, enter a new- 

line or carriage return. 

-T Specify term as the terminal type. 

-V Send output to the Versatec. Page offset is set to 1 inch. 

—x If abstracts or comments are entered following the %X field key, roffbib will format them into 
paragraphs for an annotated bibliography. Several %X fields may be given if several annotation 
paragraphs are desired. 

FILES 

/usr/lib/tmac/tmac.bib file of macros used by nroff/troff 

SEE ALSO 

"refer" in Formatting Documents on the Sun Workstation 

refer(l), addbib(l), sortbib(l), indxbib(l), lookbib(l), nroff(l) 

BUGS 

Users have to rewrite macros to create customized formats. 
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NAME 

rsh - remote shell 
SYNOPSIS 

rsh host [ -1 username ] [ -n ] command 
host [ -1 username ] [ -n ] command 

DESCRIPTION 

rsh connects to the specified host, and executes the specified command, rsh copies its standard input to the 
remote command, the standard output of the remote command to its standard output, and the standard error 
of the remote command to its standard error. Interrupt, quit and terminate signals are propagated to the 
remote command; rsh normally terminates when the remote command does. 

If you omit command, instead of executing a single command, rsh logs you in on the remote host using rlo- 
gin. 

Shell metacharacters which are not quoted are interpreted on the local machine, while quoted metacharac- 
ters are interpreted on the remote machine. Thus the command: 
tutorial% rsh lizard cat lizard.file » tutorial. file 

appends the remote file lizard.file from the machine called lizard to the file called tutorial file on the 
machine called tutorial, while the command: 

tutorial rsh lizard cat Iizard.file "»" another .lizard.file 
appends the file lizard.file on the machine called lizard to the file another. lizard.file. which also resides on 
the machine called lizard. 

Host names are given in the file /etc/hosts. Each host has one standard name (the first name given in the 
file), which is rather long and unambiguous, and optionally one or more nicknames. The host names for 
machines to which your machine is networked are also found in the directory /usr/hosts, as symbolic links 
to rsh. If you put this directory in your search path then the rsh can be omitted. 

OPTIONS 

-1 username 

use username as the remote username instead of your local username. In the absence of this 
option, the remote username is the same as your local username. This remote name must be 
equivalent to the originating account. No provision is made for specifying a password with a com- 
mand, and none is necessary — if your username is known at the remote end you will be admitted, 
otherwise you will be prompted for a password. 

-n redirect the input of rsh to Idevl null. You sometimes need this option to avoid unfortunate 
interactions between rsh and the shell which invokes it For example, if you are running csh and 
invoke a rsh in the background without redirecting its input away from the terminal, it will block 
even if no reads are posted by the remote command. The -n option will prevent this. 

The type of remote shell (sh or csh) is determined by the user’s entry in the file /etc/passwd on the remote 
system. 

FILES 

/etc/hosts 

/usr/hosts/* 

SEE ALSO 

rlogin (1C) 

BUGS 

You cannot run an interactive command (like vi; use rlogin if you wish to do so.) 

Stop signals stop the local rsh process only; this is arguably wrong, but currently hard to fix for reasons too 
complicated to explain here. 
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The current local environment is not passed to the remote shell. 

Sometimes the -n option is needed for reasons that are less than obvious. For example, the command: 

rsh somehost dd UWdev/nrmtO bs=20b | tar xvpBf - 
will put your shell into a strange state. Evidently, what happens is that the tar terminates before the rsh. 
The rsh then tries to write into the "broken pipe" and, instead of terminating neatly, proceeds to compete 
with your shell for its standard input. Invoking rsh with the -n option avoids such incidents. 

Note, however, that this bug occurs only when rsh is at the beginning of a pipeline and is not reading stan- 
dard input. Don’t use the -n if the rsh actually needs to read standard input. For example, 
tar cf - . | rsh sundial dd of=/dev/rmtO obs=20b 

doesn’t produce the bug. If you were to use the -n in a case like this, the rsh would incorrectly read from 
I dev! null instead of from the pipe. 
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NAME 

rup - show host status of local machines (RPC version) 

SYNOPSIS 

rup [ -h ] [ -I ] [ -t ] [ host ... ] 

DESCRIPTION 

R up gives a status similar to uptime for remote machines; It broadcasts on the local network, and displays 
the responses it receives. 

Normally, the listing is in the order that responses are received, but this order can be changed by specifying 
one of the options listed below. 

When host arguments are given, rather than broadcasting rup will only query the list of specified hosts. 

A remote host will only respond if it is running the rstatd daemon, which is normally started up from 
inetd(8C). 

OPTIONS 

— h sort the display alphabetically by host name. 

—1 sort the display by load average 
— t sort the display by up time. 

FILES 

/etc/servers 
SEE ALSO 

ruptime(lC), inetd(8C), rstatd(8C) 

BUGS 

Broadcasting does not work through gateways. 
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NAME 

ruptime - show host status of local machines 
SYNOPSIS 

ruptime [ —a ] [ — 1 3 [ — t ] [ — u ] 

DESCRIPTION 

Ruptime gives a status line like uptime for each machine on the local network; these are formed from pack- 
ets broadcast by each host on the network once a minute. 

Machines for which no status report has been received for 5 minutes are shown as being down. 

Normally, the listing is sorted by host name, but this order can be changed by specifying one of the options 
listed below. 

OPTIONS 

-a count even those users who have been idle for an hour or more. 

-1 sort the display by load average. 

-t sort the display by up time. 

-u sort the display by number of users. 

FILES 

/usr/spool/rwho/whod.* data files 

SEE ALSO 

rwho(lC) 
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NAME 

rusers - who’s logged in on local machines (RPC version) 

SYNOPSIS 

rusers [ -a ] [ -h ] [ -i ] [ -1 ] [ -u ] [ host . . . ] 

DESCRIPTION 

The rusers command produces output similar to users(l) and who(l), but for remote machines. It broad- 
casts on the local network, and prints the responses it receives. Normally, the listing is in the order that 
responses are received, but this order can be changed by specifying one of the options listed below. When 
host arguments are given, rather than broadcasting rusers will only query the list of specified hosts. 

The default is to print out a listing in the style of users(l) with one line per machine. When the -1 flag is 
given, a rwho(l) style listing is used. In addition, if a user hasn’t typed to the system for a minute or more, 
the idle time is reported. 

A remote host will only respond if it is running the rusersd daemon, which is normally started up from 
inetd. 

OPTIONS 

—a gives a report for a machine even if no users are logged on. 

— h sort alphabetically by host name. 

-i sort by idle time. 

-1 Give a longer listing in the style of who(l ). 

-u sort by number of users. 

FILES 

/etc/servers 
SEE ALSO 

rwho(lC), inetd(8C), rusersd(8C) 

BUGS 

Broadcasting does not work through gateways. 
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NAME 

rwall - write to all users over a network 

SYNOPSIS 

rwall hostl host2 ... 

rwall -n netgroupl netgroup2 ... 

rwall -h host -n netgroup 

DESCRIPTION 

Rwall reads a message from standard input until end-of-file. It then sends this message, preceded by the 
line “Broadcast Message ...”, to all users logged in on the specified host machines. With the -n option, it 
sends to the specified network groups, which are defined in netgroupl, 5). 

A machine can only receive such a message if it is running rwalld( 8), which is normally started up from 
letc/servers by the daemon inetd{ 8). 

FILES 

/etc/servers 
SEE ALSO 

wall(l), netgroup(5), rwalld(8), shutdown(8) 

BUGS 

The timeout is fairly short in order to be able to send to a large group of machines (some of which may be 
down) in a reasonable amount of time. Thus the message may not get thru to a heavily loaded machine. 
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NAME 

rwho - who’s logged in on local machines 
SYNOPSIS 

rwho [ -a ] 

DESCRIPTION 

The rwho command produces output similar to who( 1), but for all machines on your network. If no report 
has been received from a machine for 5 minutes, rwho assumes the machine is down, and does not report 
users last known to be logged into that machine. 

If a user hasn’t typed to the system for a minute or more, rwho reports this idle time. If a user hasn’t typed 
to the system for an hour or more, the user is omitted from the output of rwho unless the -a flag is given. 
OPTIONS 

-a report all users whether or not they have typed to the system in the past hour. 

FILES 

/usr/spool/rwho/whod.* information about other machines 

SEE ALSO 

ruptime(lC), rwhod(8C) 

BUGS 

Does not work through gateways. 

This is unwieldy when the number of machines on the local net is large. 
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NAME 

sact - print current SCCS file editing activity 

SYNOPSIS 

/usr/sccs/sact file . . . 

DESCRIPTION 

Sact informs the user of any SCCS files which have had one or more get -e commands applied to them, that 
is, there are files out for editing, and deltas are pending. If a directory is named on the command line, sact 
behaves as though each file in the directory were specified as a named file, except that non-SCCS files and 
unreadable files are silently ignored. If a name of - is given, the standard input is read with each line being 
taken as the name of an SCCS file to be processed. The output for each named file consists of five fields 
separated by spaces. 

Field 1 specifies the SID of a delta that currently exists in the SCCS file to which changes will 
be made to make the new delta. 

Field 2 specifies the SID for the new delta to be created. 

Field 3 contains the logname of the user who will make the delta (that is, executed a get for 

editing). 

Field 4 contains the date that get -e was executed. 

Field 5 contains the time that get -e was executed. 

SEE ALSO 

sccs(l), delta(l), get(l), unget(l). 

Source Code Control System in Programming Tools for the Sun Workstation. 

DIAGNOSTICS 

Use help( 1) for explanations. 
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NAME 

sees - front end for the sees subsystem 
SYNOPSIS 

sees [ -r ] [ -d prefixpath ] [ -pfinalpath ] command [ SCCS-flags ...][ file ... ] 

DESCRIPTION 

system" 

The sees command is a front end to the utility programs of the Source Code Control System (sees). 

sees normally prefixes each file, or the last component of each file, with the string SCCS/s., because you 
normally keep your SCCS database files in a directory called SCCS, and each database file starts with an 5 . 
prefix. 

Secs program options must appear before the command argument. Flags to be passed to the actual SCCS 
command (utility program) must appear after the command argument. These flags are specific to the com- 
mand being used, and are discussed in Programming Utilities for the Sun Workstation. 

Secs also includes the capability to run ‘set user id’ to another user to provide additional protection. Cer- 
tain commands (such as admin) cannot be run ‘set user id’ by all users, since this would allow anyone to 
change the authorizations. Such commands are always run as the real user. 

OPTIONS 

-r Runs secs as the real user rather than as whatever effective user secs is ‘set user id’ to. 

-d prefixpath 

Defines the prefix portion of the pathname for the SCCS database files. The default prefix portion 
of the pathname is the current directory. Prefixpath is prefixed to the entire pathname. For exam- 
ple: 

tutorial% sees -d/usr/include get sys/inode.h 
converts to: 

get /usr/include/sys/SCCS/s.inode.h 
The intent here is to create aliases such as: 

alias syssccs secs -d/usr/src 
which will be used as: 

tutorial% syssccs get cmd/who.c 

—pfinalpath 

Defines the name of a lower directory in which the SCCS files will be found; SCCS is the default 
Finalpath is appended before the final component of the pathname. For example: 

tutorial% secs -pprivate get usr/include/stdio.h 
converts to: 

get usr/include/private/s.stdio.h 
ADDITIONAL SCCS COMMANDS 

Several ‘pseudo-commands’ are available in addition to the usual SCCS commands. These are: 

admin The admin command is similar to that of the raw SCCS admin command. When creating new s. 
files, the create command (described just below) does more of the startup work for you and should 
be used in preference to admin. 

create Create is used when creating new 5. files. Given a C source language file called obscure.c, 
Create does the following actions: (1) creates the s. file called s. obscure. c in the SCCS directory; 
(2) renames the original source file to , obscure. c; (3) does an sees get on obscure. c. 

edit Get a file for editing. 

delget Perform a delta on the named files and then get new versions. The new versions have id key- 
words expanded, and so cannot be edited. 

deledit Same as delget, but produces new versions suitable for editing. Deledit is useful for making a 
‘checkpoint’ of your current editing phase. 
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fix Removes the named delta, but leaves you with a copy of the delta with the changes that were in it. 

Fix must be followed by a -r flag. Fix is useful for fixing small compiler bugs, etc. Since fix 

doesn’t leave audit trails, use it carefully. 

clean Removes everything from the current directory that can be recreated from SCCS files. Clean 
checks for and does not remove any files being edited. If Clean -b is used, branches are not 
checked to see if they are currently being edited. Note that-b is dangerous if you are keeping the 
branches in the same directory. 

unedit ‘Undoes’ the last edit or get -e and returns a file to its previous condition. If you unedit a file 
being edited, all changes made since the beginning of the editing session are lost 

info Displays a list of all files being edited. If the -b flag is given, branches (that is, SID’s with two or 
fewer components) are ignored. If the -u flag is given (with an optional argument), only files 
being edited by you (or the named user) are listed. 

check Checks for files currently being edited, like info, but returns an exit code rather than a listing: 
nothing is printed if nothing is being edited, and a non-zero exit status is returned if anything is 
being edited. Check may thus be included in an ‘install’ entry in a makefile, to ensure that every- 
thing is included in an SCCS file before a version is installed. 

tell Displays a list of files being edited on the standard output Filenames are separated by newlines. 
Takes the -b and -u flags like info and check. 

diffs Compares (in cUff-Vkt format) the current version of the program you have out for editing and the 
versions in SCCS format 

EXAMPLES 

To put a file called myprogram.c into SCCS format for the first time, assuming also that there is no SCCS 
directory already existing: 

tutorial% mkdir SCCS 
tutorial% sees create myprogram.c 

rnyprograntc: 

1.1 

14 lines 

after you have verified that everything is all right 
you remove the version of the file that starts with a comma: 
tutorial% rm , myprogram.c 
tutorials 

To get a copy of myprogram.c for editing, edit that file, then place it back in the SCCS database: 

tutorial% sees edit myprogram.c 

1.1 

new delta 1.2 
14 lines 

tutorial% vi myprogram.c 
your editing session 
tutorial% sees delget my program. c 

comments? Added abusive responses for compatibility with rest of system 

1.2 

7 inserted 
7 deleted 
7 unchanged 

1.2 

14 lines 
tutorial% 
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To get a file from another directory: 

tutorial% sees -p/usr/src/sccs/ get cc.c 
or: 

tutorial% secs get /usr/src/sccs/cc.c 
To make a delta of a large number of files in the current directory: 
tutorial% secs delta *.c 

To get a list of files being edited that are not on branches: 

tutorial% secs info -b 
To delta everything that you are editing: 

tutorial% secs delta 'secs tell -u' 

In a makefile, to get source files from an SCCS file if it does not already exist: 

SRCS = <list of source files> 

$(SRCS): 

sees get $(REL) $@ 

REGULAR SCCS COMMANDS 

The ‘regular’ SCCS commands are described very briefly below. It is unlikely that you ever need to use 
these commands because the user interface is so complicated, and the sees front end command does 99.9% 
of the interesting tasks for you. 

admin Creates new SCCS files and changes parameters of exitsing SCCS files. You can use sees create 
to create new SCCS files, or use secs admin to do other things. 

ede Changes the commentary material in an SCCS delta. 

comb Combines SCCS deltas and reconstructs the SCCS files. 

delta Permanently introduces changes that were made to a file previously retrieved via secs get. You 
can use secs delget as the more useful version of this command since secs delget does all of the 
useful work and more to boot. 

get Extracts a file from the SCCS database, either for compilation, or for editing when the -e option is 
used. Use secs get if you really need it, but secs delget will normally have done this job for you. 
Use secs edit instead of get with the -e option. 

help Supposed to help you interpret SCCS error messages, but usually just parrots the messaage and is 
generally not considered very helpful. 

prs Displays information about what is happening in an SCCS file. 

rmdel Removes a delta from an SCCS file. 

sact Displays information about editing activity in an SCCS file. The sees info command is a lot more 
useful for the real life user. 

sccsdiff Compares two versions of an SCCS file and generates the differences between the two versions. 
The secs delget command does all this work as part of its normal process. 

unget Undoes the work of a previous get -e command or a sees edit command. Use the secs unedit 
command as a useful alternative. 

val Determines if a given SCCS file meets specified criteria. If you use the secs command, you 
shouldn’t need to use val, because its user interface is unbelievable. 

what Displays SCCS identification information. 
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FILES 

/usr/sccs/* 

SEE ALSO 

admin(l), cdc(l), comb(l), delta(l), get(l), help(l), prs(l), rmdel(l), sact(l), sccsdiff(l) unget(l), val(l), 
what(l), sccsfile(5) 

Source Code Control System in Programming Utilities for the Sun Workstation 
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NAME 

sccsdiff - compare two versions of an SCCS file 
SYNOPSIS 

/usr/sccs/sccsdiff -r SIDl -r SID2 [-p ] [ -diffopts ] filenames 
DESCRIPTION 

sccsdiff compares two versions of an SCCS file and generates the differences between the two versions. 
Any number of SCCS files may be specified, but options apply to all files. 

OPTIONS 

—rSID? SIDl and SID2 specify the deltas of an SCCS file that are to be compared. Versions are 
passed to diff in the order given. 

-p pipe output for each file through pr. 

—diffopts the -c, — e, — f, — h, — b and — D options of diff cm be specified here. 

FILES 

/tmp/get????? Temporary files 
SEE ALSO 

sccs(l), diff(l), get(l), help(l), pr(l) 

Source Code Control System in Programming Tools for the Sun Workstation. 

DIAGNOSTICS 

‘ ‘ file : No differences” If the two versions are the same. 

Use help for explanations. 
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NAME 

screendump - dump frame buffer image 
SYNOPSIS 

screendump [ — f display ] [ — e ] [ — t type ] [ output-file ] 

DESCRIPTION 

Screendump reads out the contents of a frame buffer on any model of Sun Workstation and outputs the 
display image in Sun standard rasterfile format (see lusrlincludelrasterfile.h) on output-file (or on the stan- 
dard output if output-file is not specified). 

By default, screendump attempts to output the contents of the console frame buffer (Idevlfb). The -f 
option explicitly sets the name of the desired frame buffer device. 

The utility program screenload displays Sun standard rasterfiles on an appropriate Sun Workstation moni- 
tor. Output filters exist for printing standard monochrome rasterfiles on Versatec V-80 electrostatic 
plotters. 

OPTIONS 

— f display 

Use display as the device name of the display. 

-e Shorthand for -t 2. 

-t type Specify the type of the rasterfile to write: 

0 Old format files compatible with Release 1.1 software. 

1 Standard format. 

2 Run-length encoding of bytes. 

65535 To experiment with private encodings. 

EXAMPLES 

tutorial% screendump >save.this.image 

writes the current contents of the console frame buffer into the file save. this. image. 

tutorial% screendump -f /dev/cgoneO >save.co!or .image 
writes the current contents of the frame buffer Idev/cgoneO into the file save. color. image. 
tutorial% screendump | Ipr -Pversatec -v 

sends a rasterfile containing the current frame buffer to the lineprinter, selecting the printer named “versa- 
tec” and the “v” output filter (see letclprintcap). , 

FILES 

/dev/fb Default name of console display frame buffer. 

/dev/cgoneO Default name of the Sun-1 color display frame buffer. 

/dev/cgtwoO Default name of the Sun-2 color display frame buffer. 

/usr/lib/rasfilters/* Filters for the raster file 

SEE ALSO 

lpr(l), rastrepl(l), screenload(l) 

pr_dump in Programmer’ s Reference Manual for SunWindows 
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NAME 

screenload - restore frame buffer image 
SYNOPSIS 

screenload [ -d ] [ -f display ] [ -i index ] [ -b ] [ -g ] [ -p ] [ -w ] [ -h# [#### [...]]] [ input-file ] 
DESCRIPTION 

Screenload accepts input in Sun standard rasterfile format (see lusr/include/rasterfile.h ) and attempts to 
display the input on the appropriate monitor (monochrome or color). Screenload normally displays 
rasterfiles on the console display, but displays them on some heuristically determined color display if it 
finds no console display. Screenload displays color rasterfiles only on a color monitor. Screenload is able 
to display monochrome rasters on a color display. 

If the dimensions of the image contained in the input data are smaller than the actual resolution of the 
display (for example, loading a 1024-by-800 Sun-1 image on a 1152-by-900 Sun-2 display), screenload 
centers the image on the actual workstation screen and fills the border area with solid black (by default). 
Various options may be used to change the fill pattern. 

If the dimensions of the image contained in the input data are larger than the actual resolution of the 
display, screenload clips the right and bottom edges of the input image. 

If there is an optional filename argument, screenload reads its input data from that file. If no filename 
argument is given, screenload reads its input data from the standard input. 

The utility program screendump creates Sun standard rasterfiles from the display on a Sun Workstation 
monitor. 

OPTIONS 

-d Verify that display dimensions and input data image dimensions match, and print warning mes- 
sages if they do not. 

— f display 

Use display as the name of the frame buffer device. 

— i index If the image is smaller than the display, use index (0 <= index < 256) as the index value into the 
color map for the foreground color of the border fill pattern. The default index value is 255. 

-b If the input data dimensions are smaller than the display dimensions, fill the border with a pattern 
of solid ones {default). On a monochrome display this results in a black border; on a color display 
the color map value selected by the -i option determines the border color. 

-g If the input data dimensions are smaller than the display dimensions, fill the border with a pattern 
of “desktop grey”. On a monochrome display this results in a border matching the background 
pattern used by the SunWindows system; on a color display the color map value selected by the -i 
option determines the foreground border color, though the pattern is the same as on a mono- 
chrome display. 

-p Wait for a newline to be typed on the standard input before exiting. 

-w If the input data dimensions are smaller than the display dimensions, fill the border with a pattern 
of solid zeros. On a monochrome display this results in a white border; on a color display the 
color map value at index 0 determines the border color. 

-h# If the input data dimensions are smaller than the display dimensions, fill the border with the bit 
pattern described by the following # 16-bit hexadecimal constants. Note that a “1” bit is black 
and a “0” bit is white on the monochrome display; on a color diplay the color map value selected 
by the -i option determines the border foreground color. The number of hex constants in the pat- 
tern is limited to 16. 

EXAMPLES 

tutorial% screenload saved.display.image 

reloads the raster image contained in the file saved.display.image on the display type indicated by the 
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rasterfile header in that file. 

tutorial% screenload -f/dev/cgoneO monochrome image 
reloads the raster image in the file monochrome. image on the frame buffer device Idev/cgoneO. 

tutorial% screenload -hi ffff sunJLsaved.image 
is equivalent to the -b option (fill border with black), while 

tutorial% screenload -h4 8888 8888 2222 2222 sun_l.saved.image 
is equivalent to the -g option (fill border with desktop grey). 

FILES 

/dev/fb Default name of console display frame buffer 

/dev/cgoneO Default name of Sun-1 color display frame buffer 

/dev/cgtwoO Default name of the Sun-2 color display frame buffer. 

/usr/lib/ras filters/* Filters for the raster file 

SEE ALSO 

screendump(l) 

prjoad in Programmer’s Reference Manual for SunWindows 
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NAME 

script - make typescript of terminal session 
SYNOPSIS 

script [ -a ] [ file ] 

DESCRIPTION 

Script makes a typescript of everything printed on your terminal. The typescript is written to file, or 
appended to file if the -a option is given. It can be sent to the line printer later with Ipr. If no file name is 
given, the typescript is saved in the file typescript. 

The script ends when the forked shell exits. 

OPTIONS 

Append the script to the specified file instead of writing over it. 

BUGS 

Script places everything in the log file. This is not what the naive user expects. 
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NAME 

sed - stream editor 
SYNOPSIS 

sed [ — n ] [ — e script ] [ — f sfile ] [ file ] . . . 

DESCRIPTION 

Sed copies the named files (standard input default) to the standard output, edited according to a script of 
commands. 

OPTIONS 

-e Is a list of edit commands for sed. If there is just one -e option and no -f’s, the -e flag -e may be 
omitted. 

-f Take the script from sfile 

-n suppress the default output. 

SED SCRIPTS 

sed scripts consist of editing commands, one per line, of the following form: 

[address [, address] ] function [arguments] 

In normal operation sed cyclically copies a line of input into a pattern space (unless there is something left 
after a ‘D’ command), applies, in sequence, all commands whose addresses select that pattern space, and at 
the end of the script copies the pattern space to the standard output (except under -n) and deletes the pat- 
tern space. 

An address is either a decimal number that counts input lines cumulatively across files, a *$’ that addresses 
the last line of input, or a context address, ‘/regular expression/’, in the style of ed( 1) modified thus: 

The escape sequence ‘\n’ matches a newline embedded in the pattern space. 

A command line with no addresses selects every pattern space. 

A command line with one address selects each pattern space that matches the address. 

A command line with two addresses selects the inclusive range from the first pattern space that matches the 
first address through the next pattern space that matches the second. If the second address is a number less 
than or equal to the line number first selected, only one line is selected. Thereafter the process is repeated, 
looking again for the first address. 

Editing commands can be applied only to non-selected pattern spaces by use of the negation function '!’ 
(below). 

Comments. If the first nonwhite character in a line is a pound sign (#), sed treats that line as a comment, 
and ignores it. If, however, the first such line is of the form 

#n 

sed runs as if the -n flag were specified. 

In the following list of functions the maximum number of permissible addresses for each function is indi- 
cated in parentheses. 

An argument denoted text consists of one or more lines, all but the last of which end with ‘V to hide the 
newline. Backslashes in text are treated like backslashes in the replacement string of an ‘s’ command, and 
may be used to protect initial blanks and tabs against the stripping that is done on every script line. 

An argument denoted rfile or wfile must terminate the command line and must be preceded by exactly one 
blank. Each wfile is created before processing begins. There can be at most 10 distinct wfile arguments. 

(1) a\ 
text 

Append: Place text on the output before reading the next input line. 

(2) b label 
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Branch to the command bearing the label. Branch to the end of the script if label is empty. 

(2)c\ 

text 

Change: Delete the pattern space. With 0 or 1 address or at the end of a 2-address range, place 
text on the output. Start the next cycle. 

(2) d Delete the pattern space. Start the next cycle. 

(2) D Delete the initial segment of the pattern space through the first newline. Start the next cycle. 

(2) g Replace the contents of the pattern space by the contents of the hold space. 

(2) G Append the contents of the hold space to the pattern space. 

(2) h Replace the contents of the hold space by the contents of the pattern space. 

(2) H Append the contents of the pattern space to the hold space. 

d)i\ 

text 

Insert: Place text on the standard output. 

(2)n Copy the pattern space to the standard output Replace the pattern space with the next line of 
input. 

(2)N Append the next line of input to the pattern space with an embedded newline. (The current line 
number changes.) 

(2) p Print: Copy the pattern space to the standard output. 

(2) P Copy the initial segment of the pattern space through the first newline to the standard output. 

(1) q Quit: Branch to the end of the script. Do not start a new cycle. 

(2) r rfile 

Read the contents of rfile. Place them on the output before reading the next input line. 

(2) s / regular expression/replacement/flags 

Substitute the replacement string for instances of the regular expression in the pattern space. Any 
character may be used instead of 7’. For a fuller description see ed{ 1). Flags is zero or more of 

g Global: Substitute for all nonoverlapping instances of the regular expression rather than 
just the first one. 

p Print the pattern space if a replacement was made, 
w wfile Write: Append the pattern space to wfile if a replacement was made. 

(2) t label 

Test: Branch to the command bearing the label if any substitutions have been made since the 
most recent reading of an input line or execution of a ‘t’. If label is empty, branch to the end of 
the script. 

(2) w wfile 

Write: Append the pattern space to wfile. 

(2) x Exchange the contents of the pattern and hold spaces. 

(2) y Istringl/string2/ 

Transform: Replace all occurrences of characters in stringl with the corresponding character in 
string2. The lengths of stringl and string2 must be equal. 

(2)! function 

Don’t: Apply the function (or group, if function is ‘{’) only to lines not selected by the 
address(es). 

(0) : label 
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This command does nothing; it bears a label for ‘b’ and ‘t’ commands to branch to. Note that the 
maximum length of label is seven characters. 

(1) = Place the current line number on the standard output as a line. 

(2) { Execute the following commands through a matching *}’ only when the pattern space is selected. 

(0) An empty command is ignored. 


SEE ALSO 

Using UNIX Text Utilities on the Sun Workstation Editing Text Files on the Sun Workstation 
ed(l), grep(l), awk(l), lex(l) 
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NAME 

setkeys - modify the interpretation of keyboard keys 
SYNOPSIS 

setkeys [ reset | nosunview | [ [lefty ] [ noarrows ] ] ] [ sunl | sun2 1 sun3 ] 

DESCRIPTION 

Setkeys changes the kernel’s keyboard translation tables, converting a keyboard to one of a number of com- 
monly desired configurations. It takes an indication of the modifications to be performed, and optionally, 
the kind of keyboard attached to the user’s machine. It affects all keyboard input for the machine it is run 
on (in or out of the window system) until that effect is superseded by rebooting, or by running "setkeys 
reset". 

Normally, users should set their /etc/rc.local to run setkeys with appropriate arguments when their machine 
is booted. 


OPTIONS 

modifications 


Lefty 


Noarrows 

Nosunview 


Reset 

keyboard type 


Empty, "reset", "nosunview", or some combination of "lefty" and "noarrows". 

By default, the keyboard is set to produce the SunView function-key codes (Stop, Props, 
Front, Close, Find, Again, Undo, Put, Get and Erase; <REF SunView documentation:*). 
On Sun2 and Sun3 keyboards, this is a no-op; on the Sunl, those functions are assigned 
to two columns of the right numeric / function pad. 

indicates the SunView functions are to be produced from keys on the right side of the 
keyboard, convenient for using the mouse in the left hand. 

On the Sun2 and Sun3, the SunView functions are reflected to the outside columns of the 
right function pad; those right-side functions are distributed in a more complicated 
fashion dictated by keeping the arrow keys together; see below. Also, the Line Feed key, 
immediately below Return, is converted to a second Control. 

On the Sunl, "lefty" is the same as the default, since there is no left function pad. 

reassigns the keys with cursor arrows on their caps to produce simple function codes (so 
they may be used with filters in the textsw, or mapped input in the ttysw). 

valid only on a Sun2 or Sun3 keyboard, and incompatible with "lefty”, "noarrows", or 
""reset." This option assigns new codes to keys FI and L2 - L10, codes that are not nor- 
mally produced anywhere on the keyboard. These codes may be selected by a mapi or 
mapo operation defined in a user’s .ttyswrc file. 

This option supports a measure of backwards compatibility to programs that apply some 
other interpretation to the affected function keys. It allows them to access the new codes 
when the standard codes would be preempted by SunView functions (e.g. in a tty 
subwindow). 

is incompatible with "lefty", "noarrows", or "nosunview"; it causes the keyboard to be 
reset to its original interpretation. 

One of Sunl, Sun2, or Sun3. 

Normally, this option is omitted; the type of keyboard attached to the system is obtained 
from the kernel. If included, the option is believed in preference to the kernel’s informa- 
tion. Setkeys treats Sun2 and Sun3 keyboards identically except when the modification is 
"reset." 


Note the keyboard type is not necessarily the same as the machine type: A Sunl keyboard is the VT1 00-style 
keyboard shipped with Model lOOUs, while Sun2 and Sun3 keyboards may be attached interchangeably to 
Sun-2 and Sun-3 machines. A Sun3 keyboard is distinguished by its aerodynamic housing, and the presence of 
Caps and Alternate keys. 
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Options may appear in any order, and case is not significant. The accompanying charts show the exact dis- 
tribution of codes for each combination of keyboard and arguments to setkeys. 

EXAMPLES 

setkeys lefty noarrows 

puts the SunView functions on the right pad of the keyboard, replacing arrow keys by the corresponding 
right-function codes, and displacing right-function codes to the left pad. 

setkeys sunl reset 

restores a Sunl keyboard to its original arrangement 

SEE ALSO 

KB(4S), KBD(5) 

BUGS 

DIAGRAMS 

Sunl, reset: 

A V < > 

[ standard ] TF1 
[ typing ] 

[ array ] 

[ .... ] 


default / lefty: 

A V < > 

[ standard ] Again RF1 Stop 
[ typing ] Undo RF3 

[ array ] Put RF5 

[ .... ] Get RF7 

Delete Find 


default / lefty, noarrow: 

TF1 TF2 TF3 TF4 

[ standard ] Again RF1 Stop 
[ typing ] Undo RF3 

[ array ] Put RF5 

[ .... ] Get RF7 

Delete Find 


RF2 

Props RF4 
Front RF6 
Close RF8 


RF2 

Props RF4 
Front RF6 
Close RF8 


TF2 TF3 TF4 

7 8 9 - 

4 5 6, 

1 2 3 En- 

0 . ter 
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Sun2 & Sun3, 


reset / default: 



Stop 

Again 

TF1 TF2 ... 

[ standard 

Props 

Undo 

t 

typing 

Front 

Put 

[ 

array 

Close 

Get 

[ 


Find 

Delete 

[ 



noarrows (only): 



Stop 

Again 

TF1 TF2 ... 

[ standard 

Props 

Undo 

[ 

typing 

Front 

Put 

[ 

array 

Close 

Get 

[ 


Find 

Delete 

[ 



lefty: 






TF1 TF2 ... 

Stop 

RF1 

[ 

standard 

RF6 

RF4 

[ 

typing 

RF9 

RF7 

[ 

array 

RF12 

RF10 

t 


RF15 

RF13 

[ 
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RF6 

RF4 

[ 
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nosunview: 





LF11 TF2 ... 
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LF13 

TF13 

[ 

array 
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NAME 

sh - shell, the standard command programming language 
SYNOPSIS 

sh [ -acefhiknstuvx ] [ args ] 

DESCRIPTION 

Sh is a command programming language that executes commands read from a terminal or a file. See Invo- 
cation below for the meaning of arguments to the shell. 

Definitions 

A blank is a tab or a space. A name is a sequence of letters, digits, or underscores beginning with a letter 
or underscore. A parameter is a name, a digit, or any of the characters *, @, #, ?, $, and ! . 

Commands 

A simple-command is a sequence of non-blank words separated by blanks. The first word specifies the 
name of the command to be executed. Except as specified below, the remaining words are passed as argu- 
ments to the invoked command. The command name is passed as argument 0 (see exec (2)). The value of 
a simple-command is its exit status if it terminates normally, or (octal) 200 +status if it terminates abnor- 
mally (see sigvec(2) for a list of status values). 

A pipeline is a sequence of one or more commands separated by | (or, for historical compatibility, by ‘). 
The standard output of each command but the last is connected by a pipe {2) to the standard input of the 
next command. Each command is run as a separate process; the shell waits for the last command to ter- 
minate. The exit status of a pipeline is the exit status of the last command. 

A list is a sequence of one or more pipelines separated by &, &&, or | |, and optionally terminated by ; 
or &. Of these four symbols, ; and & have equal precedence, which is lower than that of && and | |. The 
symbols && and | | also have equal precedence. A semicolon (;) causes sequential execution of the 
preceding pipeline; an ampersand (&) causes asynchronous execution of the preceding pipeline (i.e., the 
shell does not wait for that pipeline to finish). The symbol && ( | |) causes the list following it to be exe- 
cuted only if the preceding pipeline returns a zero (non-zero) exit status. An arbitrary number of new-lines 
may appear in a list, instead of semicolons, to delimit commands. 

A command is either a simple-command or one of the following. Unless otherwise stated, the value 
returned by a command is that of the last simple-command executed in the command. 

for name [ in word ... ] do list done 

Each time a for command is executed, name is set to the next word taken firom the in word list. If 
in word ... is omitted, then the for command executes the do list once for each positional param- 
eter that is set (see Parameter Substitution below). Execution ends when there are no more words 
in the list. 

case word in [ pattern [ | pattern ] . . . ) list ;; ] . . . esac 

A case command executes the list associated with the first pattern that matches word. The form 
of the patterns is the same as that used for file-name generation (see File Name Generation) 
except that a slash, a leading dot, or a dot immediately following a slash need not be matched 
explicitly. 

if list then list [ elif list then list ] . . . [ else list ] fi 

The list following if is executed and, if it returns a zero exit status, the list following the first then 
is executed. Otherwise, the list following elif is executed and, if its value is zero, the list follow- 
ing the next then is executed. Failing that, the else list is executed. If no else list or then list is 
executed, then the if command returns a zero exit status, 
while list do list done 

A while command repeatedly executes the while list and, if the exit status of the last command in 
the list is zero, executes the do list; otherwise the loop terminates. If no commands in the do list 
are executed, then the while command returns a zero exit status; until may be used in place of 
while to negate the loop termination test. 

(list) 
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Execute list in a sub-shell. 

{list;} 

list is simply executed. 
name () {list;} 

Define a function which is referenced by name. The body of the function is the list of commands 
between { and }. Execution of functions is described below (see Execution). 

The following words are only recognized as the first word of a command and when not quoted: 

if then else elif fi case esac for while until do done { } 

Comments 

A word beginning with # causes that word and all the following characters up to a new-line to be ignored. 
Command Substitution 

The standard output from a command enclosed in a pair of grave accents (" ) may be used as part or all of 
a word; trailing new-lines are removed. 

Parameter Substitution 

The character $ is used to introduce substitutable parameters. There are two types of parameters, posi- 
tional and keyword. If parameter is a digit, it is a positional parameter. Positional parameters may be 
assigned values by set. Keyword parameters (also known as variables) may be assigned values by writing: 

name -value [ name -value ] ... 

Pattern-matching is not performed on value. There cannot be a function and a variable with the same 
name. 

${ parameter } 

The value, if any, of the parameter is substituted. The braces are required only when parameter is 
followed by a letter, digit, or underscore that is not to be interpreted as part of its name. If param- 
eter is * or @, all the positional parameters, starting with $1, are substituted (separated by spaces). 
Parameter $0 is set from argument zero when the shell is invoked. 

${parame ter:— word} 

If parameter is set and is non-null, substitute its value; otherwise substitute word. 

${parame ten-word} 

If parameter is not set or is null set it to word ; the value of the parameter is substituted. Positional 
parameters may not be assigned to in this way. 

%{parameter:1word} 

If parameter is set and is non-null, substitute its value; otherwise, print word and exit from the 
shell. If word is omitted, the message “parameter null or not set” is printed. 

${parameter:+word} 

If parameter is set and is non-null, substitute word; otherwise substitute nothing. 

In the above, word is not evaluated unless it is to be used as the substituted string, so that, in the following 
example, pwd is executed only if d is not set or is null: 

echo ${d:- N pwd v } 

If the colon (:) is omitted from the above expressions, the shell only checks whether parameter is set or 
not. 

The following parameters are automatically set by the shell: 

# The number of positional parameters in decimal. 

- Flags supplied to the shell on invocation or by the set command. 

? The decimal value returned by the last synchronously executed command. 

$ The process number of this shell. 

! The process number of the last background command invoked. 
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The following parameters are used by the shell: 

HOME The default argument (home directory) for the cd command. 

PATH The search path for commands (see Execution below). 

CDPATH 

The search path for the cd command. 

MAR, If this parameter is set to the name of a mail file and the mailpath parameter is not set, 
the shell informs the user of the arrival of mail in the specified file. 

MAELCHECK 

This parameter specifies how often (in seconds) the shell will check for the arrival of 
mail in the files specified by the mailpath or mail parameters. The default value is 600 
seconds (10 minutes). If set to 0, the shell will check before each prompt 
MAILPATH 

A colon (:) separated list of file names. If this parameter is set, the shell informs the user 
of the arrival of mail in any of the specified files. Each file name can be followed by % 
and a message that will be printed when the modification time changes. The default mes- 
sage is you have mail. 

PSI Primary prompt string, by default “$ ”. 

PS2 Secondary prompt string, by default “> ” . 

IFS Internal field separators, normally space, tab, and new-line. 

SHELL When the shell is invoked, it scans the environment (see Environment below) for this 
name. If it is found and there is an ’r’ in the file name part of its value, the shell becomes 
a restricted shell. 

The shell gives default values to path, PSl, PS2, mailcheck and ifs. HOME and MAIL are set by 
login( 1). 

Blank Interpretation 

After parameter and command substitution, the results of substitution are scanned for internal field separa- 
tor characters (those found in IFS) and split into distinct arguments where such characters are found. Expli- 
cit null arguments ("" or - ') are retained. Implicit null arguments (those resulting from parameters that 
have no values) are removed. 

File Name Generation 

Following substitution, each command word is scanned for the characters *, ?, and [ . If one of these char- 
acters appears the word is regarded as a pattern. The word is replaced with alphabetically sorted file 
names that match the pattern. If no file name is found that matches the pattern, the word is left unchanged. 
The character . at the start of a file name or immediately following a /, as well as the character / itself, must 
be matched explicitly. 

* Matches any string, including the null string. 

? Matches any single character. 

[ . . . ] Matches any one of the enclosed characters. A pair of characters separated by - matches 
any character lexically between the pair, inclusive. If the first character following the 
opening "[ " is a “!” any character not enclosed is matched. 

Quoting 

The following characters have a special meaning to the shell and cause termination of a word unless 
quoted: 

; & ( ) | * < > new-line space tab 

A character may be quoted (i.e., made to stand for itself) by preceding it with a \. The pair \new-Iine is 
ignored. All characters enclosed between a pair of single quote marks l"), except a single quote, are 
quoted. Inside double quote marks (""), parameter and command substitution occurs and \ quotes the char- 
acters \, ' , ", and $. "$*" is equivalent to "$1 $2 . . .", whereas is equivalent to "$1" "$2" — 
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Prompting 

When used interactively, the shell prompts with the value of PS1 before reading a command. If at any time 
a new-line is typed and further input is needed to complete a command, the secondary prompt (i.e., the 
value of PS2) is issued. 


Input/Output 

Before a command is executed, its input and output may be redirected using a special notation interpreted 
by the shell. The following may appear anywhere in a simple-command or may precede or follow a com- 
mand and are not passed on to the invoked command; substitution occurs before word or digit is used: 


<word 

>word 

»word 

<*c[-]word 


<&digit 

<&— 


Use file word as standard input (file descriptor 0). 

Use file word as standard output (file descriptor 1). If the file does not exist it is created; 
otherwise, it is truncated to zero length. 

Use file word as standard output. If the file exists output is appended to it (by first seek- 
ing to the end-of-file); otherwise, the file is created. 

The shell input is read up to a line that is the same as word, or to an end-of-file. The 
resulting document becomes the standard input. If any character of word is quoted, no 
interpretation is placed upon the characters of the document; otherwise, parameter and 
command substitution occurs, (unescaped) \new-line is ignored, and \ must be used to 
quote the characters \, $, ', and the first character of word. If - is appended to «*:, all 
leading tabs are stripped from word and from the document 

Use the file associated with file descriptor digit as standard input. Similarly for the stan- 
dard output using >&digit. 

The standard input is closed. Similarly for the standard output using >&-. 


If any of the above is preceded by a digit, the file descriptor which will be associated with the file is that 
specified by the digit (instead of the default 0 or 1). For example: 


... 2>&1 


associates file descriptor 2 with the file currently associated with file descriptor 1. 

The order in which redirections are specified is significant. The shell evaluates redirections left-to-right 
For example: 

... l>xxt 2>&1 

first associates file descriptor 1 with file xxx. It associates file descriptor 2 with the file associated with file 
descriptor 1 (i.e. xxx). If the order of redirections were reversed, file descriptor 2 would be associated with 
the terminal (assuming file descriptor 1 had been) and file descriptor 1 would be associated with file xxx. 

If a command is followed by & the default standard input for the command is the empty file /dev/null. 
Otherwise, the environment for the execution of a command contains the file descriptors of the invoking 
shell as modified by input/output specifications. 

Redirection of output is not allowed in the restricted shell. 

Environment 

The environment (see environ (5)) is a list of name-value pairs that is passed to an executed program in the 
same way as a normal argument list. The shell interacts with the environment in several ways. On invoca- 
tion, the shell scans the environment and creates a parameter for each name found, giving it the 
corresponding value. If the user modifies the value of any of these parameters or creates new parameters, 
none of these affects the environment unless the export command is used to bind the shell’s parameter to 
the environment (see also set -a). A parameter may be removed from the environment with the unset com- 
mand. The environment seen by any executed command is thus composed of any unmodified name-value 
pairs originally inherited by the shell, minus any pairs removed by unset, plus any modifications or addi- 
tions, all of which must be noted in export commands. 

The environment for any simple-command may be augmented by prefixing it with one or more assignments 
to parameters. Thus: 
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term= 450 cmd and 

(export term; term= 450; cmd) 

are equivalent (as far as the execution of cmd is concerned). 

If the -k flag is set, all keyword arguments are placed in the environment, even if they occur after the com- 
mand name. The following first prints a=b c and c: 

echo a=b c 
set -k 
echo a=b c 

Signals 

The interrupt and quit signals for an invoked command are ignored if the command is followed by &; 
otherwise signals have the values inherited by the shell from its parent, with the exception of signal 1 1 (but 
see also the trap command below). 

Execution 

Each time a command is executed, the above substitutions are carried out If the command name matches 
one of the Special Commands listed below, it is executed in the shell process. If the command name does 
not match a Special Command, but matches the name of a defined function, the function is executed in the 
shell process (note how this differs from the execution of shell procedures). The positional parameters $1, 
$2 are set to the arguments of the function. If the command name matches neither a Special Com- 

mand nor the name of a defined function, a new process is created and an attempt is made to execute the 
command via exec (2). 

The shell parameter PATH defines the search path for the directory containing the command. Alternative 
directory names are separated by a colon (:). The default path is :/bin:/usr/bin (specifying the current 
directory, /bin, and /usr/bin, in that order). Note that the current directory is specified by a null path name, 
which can appear immediately after the equal sign or between the colon delimiters anywhere else in the 
path list. If the command name contains a / the search path is not used; such commands will not be exe- 
cuted by the restricted shell. Otherwise, each directory in the path is searched for an executable file. If the 
file has execute permission but is not an a.out file, it is assumed to be a file containing shell commands. A 
sub-shell is spawned to read it. A parenthesized command is also executed in a sub-shell. 

The location in the search path where a command was found is remembered by the shell (to help avoid 
unnecessary execs later). If the command was found in a relative directory, its location must be re- 
determined whenever the current directory changes. The shell forgets all remembered locations whenever 
the PATH variable is changed or the hash -r command is executed (see below). 

Special Commands 

Input/output redirection is now permitted for these commands. File descriptor 1 is the default output loca- 
tion. 

: No effect; the command does nothing. A zero exit code is returned. 

. file Read and execute commands from file and return. The search path specified by PATH is used to 

find the directory containing file. 
break [ n ] 

Exit from the enclosing for or while loop, if any. If n is specified break n levels, 
continue [ n ] 

Resume the next iteration of the enclosing for or while loop. If n is specified resume at the n-th 
enclosing loop, 
cd [ arg ] 

Change the current directory to arg. The shell parameter HOME is the default arg. The shell 
parameter CDPATH defines the search path for the directory containing arg. Alternative directory 
names are separated by a colon (:). The default path is <null> (specifying the current directory). 
Note that the current directory is specified by a null path name, which can appear immediately 
after the equal sign or between the colon delimiters anywhere else in the path list. If arg begins 
with a / the search path is not used. Otherwise, each directory in the path is searched for arg . 


298 


Last change: 26 August 1985 


Sun Release 3.0 



SH(1) 


USER COMMANDS 


SH( 1 ) 


echo [ arg . . . ] 

Echo arguments. See echo(l) for usage and description, 
eval [ arg ... ] 

The arguments are read as input to the shell and the resulting command(s) executed, 
exec [ arg ... ] 

The command specified by the arguments is executed in place of this shell without creating a new 
process. Input/output arguments may appear and, if no other arguments are given, cause the shell 
input/output to be modified, 
exit [ n ] 

Causes a shell to exit with the exit status specified by n. If n is omitted the exit status is that of the 
last command executed (an end-of-file will also cause the shell to exit.) 
export [ name . . . ] 

The given name s are marked for automatic export to the environment of subsequently-executed 
commands. If no arguments are given, a list of all names that are exported in this shell is printed. 
Function names may not be exported, 
hash [ — r ] [ name . . . ] 

For each name , the location in the search path of the command specified by name is determined 
and remembered by the shell. The -r option causes the shell to forget all remembered locations. 
If no arguments are given, information about remembered commands is presented. Hits is the 
number of times a command has been invoked by the shell process. Cost is a measure of the work 
required to locate a command in the search path. There are certain situations which require that 
the stored location of a command be recalculated. Commands for which this will be done are 
indicated by an asterisk (*) adjacent to the hits information. Cost will be incremented when the 
recalculation is done, 
login [arg ... ] 

Equivalent to exec login arg .... See login( 1) for usage and description, 
pwd Print the current working directory. See pwd(l) for usage and description, 
read [ name . . . ] 

One line is read from the standard input and the first word is assigned to the first name, the second 
word to the second name, etc., with leftover words assigned to the last name. The return code is 0 
unless an end-of-file is encountered, 
readonly [ name . . . ] 

The given name s are marked readonly and the values of the these name s may not be changed by 
subsequent assignment. If no arguments are given, a list of all readonly names is printed, 
return [ n ] 

Causes a function to exit with the return value specified by n. If n is omitted, the return status is 
that of the last command executed, 
set [ — aefhkntuvx [ arg . . . ] ] 

-a Mark variables which are modified or created for export 
-e Exit immediately if a command exits with a non-zero exit status. 

-f Disable file name generation 

-h Locate and remember function commands as functions are defined (function commands 
are normally located when the function is executed). 

-k All keyword arguments are placed in the environment for a command, not just those that 
precede the command name. 

-n Read commands but do not execute them. 

-t Exit after reading and executing one command. 

-u Treat unset variables as an error when substituting. 

-v Print shell input lines as they are read. 

-x Print commands and their arguments as they are executed. 

— Do not change any of the flags; useful in setting $1 to -. 

Using + rather than - causes these flags to be turned off. These flags can also be used upon invo- 
cation of the shell. The current set of flags may be found in $-. The remaining arguments are 
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positional parameters and are assigned, in order, to $1, $2, If no arguments are given the 

values of all names are printed, 
shift [ n ] 

The positional parameters from $n+l ... are renamed $1 If n is not given, it is assumed to be 

1. 

test 

Evaluate conditional expressions. See test( 1) for usage and description. 

times 

Print the accumulated user and system times for processes run from the shell, 
trap [ arg ] [ n ] . . . 

The command arg is to be read and executed when the shell receives signal(s) n. (Note that arg is 
scanned once when the trap is set and once when the trap is taken.) Trap commands are executed 
in order of signal number. Any attempt to set a trap on a signal that was ignored on entry to the 
current shell is ineffective. An attempt to trap on signal 1 1 (memory fault) produces an error. If 
arg is absent all trap(s) n are reset to their original values. If arg is the null string this signal is 
ignored by the shell and by the commands it invokes. If n is 0 the command arg is executed on 
exit from the shell. The trap command with no arguments prints a list of commands associated 
with each signal number, 
type [ name . . . ] 

For each name, indicate how it would be interpreted if used as a command name, 
umask [ ooo ] 

The user file-creation mode mask is set to ooo. The three octal digits refer to read/write/execute permis- 
sions for owner, group, and others, respectively. The value of each specified digit is subtracted from the 
corresponding ‘digit’ specified by the system for the creation of a file. For example, umask 022 removes 
group and others write permission (files normally created with mode 111 become mode 755; files created 
with mode 666 become mode 644). 

The current value of the mask is printed if ooo is omitted, 
unset [ name . . . ] 

For each name, remove the corresponding variable or function. The variables path, psi, PS2, 
MAILCHECK and IFS cannot be unset, 
wait [ n ] 

Wait for the specified process and report its termination status. If n is not given all currently 
active child processes are waited for and the return code is zero. 

Invocation 

If the shell is invoked through exec (2) and the first character of argument zero is -, commands are initially 
read from $HOME/.profile, if such files exist. Thereafter, commands are read as described below, which is 
also the case when the shell is invoked as /bin/sh. The flags below are interpreted by the shell on invoca- 
tion only; Note that unless the -c or -s flag is specified, the first argument is assumed to be the name of a 
file containing commands, and the remaining arguments are passed as positional parameters to that com- 
mand file: 

-c string If the -c flag is present commands are read from string . 

-s If the -s flag is present or if no arguments remain commands are read from the standard input. 

Any remaining arguments specify the positional parameters. Shell output (except for Special 
Commands) is written to file descriptor 2. 

-i If the -i flag is present or if the shell input and output are attached to a terminal, this shell is 

interactive. In this case terminate is ignored (so that kill 0 does not kill an interactive shell) 
and INTERRUPT is caught and ignored (so that wait is interruptible). In all cases, QUIT is 
ignored by the shell. 

The remaining flags and arguments are described under the set command above. 

EXIT STATUS 

Errors detected by the shell, such as syntax errors, cause the shell to return a non-zero exit status. If the 
shell is being used non-interactively execution of the shell file is abandoned. Otherwise, the shell returns 
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the exit status of the last command executed (see also the exit command above). 

FILES 

$HOME/.profile 

/tmp/sh* 

/dev/null 

SEE ALSO 

csh(l), cd( 1), echo(l), login(l), pwd(l), test(l), dup(2), exec(2), fork(2), pipe®, signal(2), umask(2), 
wait(2), a.out(5), profile®, environ®. 

CAVEATS 

If a command is executed, and a command with the same name is installed in a directory in the search path 
before the directory where the original command was found, the shell will continue to exec the original 
command. Use the hash command to correct this situation. 

If you move the current directory or one above it, pwd may not give the correct response. Use the cd com- 
mand with a full path name to correct this situation. 
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NAME 

shelltool - Run a shell (or other program) in the SunView environment 
SYNOPSIS 

shelltool [ — C ] [ — B boldstyle ] [ program [ args ]] 

DESCRIPTION 

shelltool is a standard tool provided with the SunView environment. 

When invoked, shelltool runs a program, (usually a shell) in an interactive terminal emulator based on a tty 
subwindow. Keystrokes typed to the shelltool are passed to the program running in the shelltool. If this 
program is a shell, it accepts commands and runs programs in the usual way. For its scrolling and editting 
capabilities, you may prefer to use cmdtool instead of shelltool. See cmdtool( 1), suntools( 1), Terminal 
Emulators, and Windows and Window-Based Tools: Beginner’s Guide for more information. 

To run graphics programs, use gfxtool — see gfxtool( 1). 

DEFAULTS OPTIONS 
/Tty/Bold_style 

For programs that use emphasized text, shelltool supports bolding as well as inverse video. To set 
the emphasis style, choose the category Tty in defaultsedit and choose one of the following for the 
Bold style entry: 

None disables emphasis 

Offset_X thicken character horizontally 

OffsetY thicken character vertically 

Offset_X_and_Y thicken character both horizontally and vertically 

Offset_XY thicken character diagonally 

OffsetXandXY thicken character both horizontally and diagonally 

Offset_Y_and_XY thicken character both vertically and diagonally 

Offset_X_and_Y_and_XY thicken character horizontally, vertically and diagonally 

Invert display emphasis as inverse video, the standard default 

/Tty/Retained 

No is the standard default; it specifies that tty subwindows are not retained. If Yes is chosen, tty 
subwindows are retained; this enhances display speed at the expense of memory consumption. 
Repaint speed when the window is uncovered is greatly enhanced. 

COMMANDLINE OPTIONS 

-C Redirect system console output to this instance of the shelltool. 

-B boldstyle 

Sets the boldstyle for this instance of shelltool. Boldstyle may be any of the choices for the 
defaults database entry for /Tty/Bold_style, or it may be a number from 0 to 8. The numbers 
mean: 

0 None 

1 Offset_X 

2 Offset_Y 

3 Offset_X_and_Y (means Offset_X | Offset Y) 

4 Offset_XY 

5 Offset_X_and_XY (means Offset_X | Offset_XY) 

6 Offset_Y_and_XY (means Offset_Y | Offset XY) 

7 Offset_X_and_Y_and_XY (means Offset_X | Offset_Y | Offset_XY) 

8 Invert 

shelltool also takes generic tool arguments; see s untools (1) for a list of these arguments. 

If a program argument is present, shelltool runs it. If there are no arguments, shelltool runs the program 
corresponding to your SHELL environment variable. If this environment variable is not available, then 
shelltool runs /bin/sh. 
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THE TERMINAL EMULATOR 

The tty subwindow of shelltool is a terminal emulator. Whenever a tty subwindow is created, the startup 
file '/.ttyswrc is parsed for tty subwindow-specific parameters. A sample .ttyswrc file may be found in 
/usr/lib/ttyswrc. The command format of this file is: 


# Comment 

set variable Turn on the specified variable. 

mapi key text When key is typed pretend text was input. 

mapo key text When key is typed pretend text was output. 

The only currently defined "variable" is "pagemode". "Key" is one of L1-L15, F1-F15, T1-T15, R1-R15, 
LEFT, or RIGHT (see note below). "Text" may contain escapes such as \E, \n, “X, etc. (escape,’ newline,’ 
control-X, respectively). See termcap( 5) for the format of the string escapes that are recognized. Note that 
"mapi" and "mapo" may be replaced by another keymapping mechanism in the future. 


NOTE: When using the default kernel keyboard tables, the keys LI, LEFT, RIGHT, BREAK, R8, RIO, 
R12, and R14 cannot be mapped in this way because they send special values to the tty subwindow. Also, 
when using the default kernel keyboard tables, L1-L10 are now used by SunView. See setkeys{\) and 
kbd (5) for more information on how to change the behavior of the keyboard. 

It is possible to have terminal-based programs drive the tool in which its tty subwindow resides by sending 
it special escape sequences. These escape sequences may also be sent by typing a key appropriately 
mapped using the "mapo" function described above. The following functions pertain to the tool in which 
the tty subwindow resides, not the tty subwindow itself. 


\E [It 

-open 

\E[2t 

- close (become iconic) 

\E[3t 

- move, with interactive feedback 

\E [ 3 ; TOP ; LEFTt 

- move, to TOP left (pixel coordinates) 

\E[4t 

- stretch, with interactive feedback 

\E[4;WIDTH;HTt 

- stretch, to WIDTH HT size (in pixels) 

\E[5t 

- expose 

\E[6t 

-hide 

\E [ 7 1 

- refresh 

\E [ 8 ; ROWS ; COLSt 

- stretch, to ROWS COLS size (in characters) 

\E [lit 

- report if open or iconic by sending \E[ltor\E[2t 

\E[13t 

- report position by sending \E [ 3 ; TOP ; LEFTt 

\E[14t 

- report size in pixels by sending \E ( 4 ; WIDTH ; HTt 

\E[18t 

- report size in characters by sending \E [ 8 ; ROWS ; COLSt 

\E [20t 

- report icon label by sending \E] Llabel\E\ 

\E[21t 

- report tool header by sending \E] llabel\E\ 

\E] l<text>\E\ 

- set tool header to <text> 

\E] I<file>\E\ 

- set icon to the icon contained in <f ile>; 

<f ile> must be in iconedit output format 

\E]L<label>\E\ 

- set icon label to <label> 

\E [>OPT; . . .h 

- turn OPT on (OPT = 1 => pagemode), e.g., \E [ >1 ; 3 ; 4h 

\E [>OPT; . . .k 

- report OPT; sends \E [>OPTl or \E [>OPTh for each OPT 

\E [>OPT; . . .1 

- turn OPT off (OPT = 1 => pagemode), e.g., \E [>1; 3; 41 


As an example of using this facility, the following aliases can be put into your '/.cshrc file: 

# dynamically set the name stripe of the tool: 
alias header 'echo -n "\E] 1\ ! *\E\"' 

# dynamically set the label on the icon: 

alias iheader 'echo -n "\E] L\ ! *\E\"' 

# dynamically set the image on the icon: 
alias icon 'echo -n "\E] I\ ! *\E] \"' 


Sun Release 3.0 


Last change: 30 September 1985 


303 



SHELLTOOL ( 1 ) 


USER COMMANDS 


SHELLTOOL ( 1 ) 


Selections 

Terminal subwindows support a facility called selection, which provides for limited inter-tool communica- 
tion and mouse-oriented text manipulation. A selection is a span of characters which you can manipulate. 
To make a selection: 

• Press the select (left) mouse button while the tip of the cursor is over the desired character. Your selec- 
tion becomes highlighted (video inverted). This feedback helps you see what you’re doing. Any previ- 
ous selections in any window are de-selected; the highlighting around the old selection disappears. 
Move the mouse with the select button down, and the selection changes. Release the select button to 
complete the selection. 

• Press the adjust (middle) mouse button down and move the mouse to change the span of characters that 
you select. Release the button. All characters, from the ones you originally selected through the one 
indicated when you released adjust, are selected. The highlighting indicating the selection adjusts to 
reflect its new contents. 

You can also adjust your selection by multi-clicking. If clicks are less than .5 seconds apart, they combine 
into a multiple click. For example, if you click twice on a character, the highlighting adjusts to select a 
word (non-white-space delimited by white-space). Click three (3) times, and the highlighting adjusts to 
select a line. You can select characters obscured by another window if they lie between the characters you 
chose as the endpoints to the selection. The selection is deselected if you type any key or any new output is 
written to the window which holds the selection. 

Menu 

To manipulate your selection, press the menu button over the terminal subwindow. A ttysw menu appears 
with the menu items discussed below: 

Put, then Get 

When there is a selection in any window, this item reads Put, then Get. Selecting it copies the 
selection both to the shelf and to the insertion point (cursor). It copies selections in tty, text, com- 
mand, and panel subwindows. It is intended to bridge the gap between Stuff and the new selec- 
tion functionality (see Windows and Window-Based Tools: Beginner’s Guide and cmdtool(l)). 

Put, then Get 

When there is no selection but there is text on the shelf. Put, then is grayed out, though Get 
remains active. Selecting this item causes the contents of the shelf to be copied to the insertion 
point (cursor). When there is no selection and nothing on the shelf, this item is inactive. 

Page Mode On 

Select Page Mode On to prevent voluminous tty subwindow output from scrolling off the screen. 
Page Mode can save you from redoing a command with a pipe to more in such cases. 

When Page Mode is on, the cursor becomes a tiny stop sign when a command generates a screen- 
ful of output. To restart output, type any key, or select the Continue menu item, which tem- 
porarily replaces Page Mode On. When there is no output waiting to be shown, the cursor 
remains in the shape of an arrow, and Page Mode Off replaces Page Mode On in the menu. 

Stuff is provided for backward compatibility. Select Stuff, and the characters in the selection are 
copied to the insertion point (cursor) as though they had been typed at the keyboard. The window 
in which you invoke Stuff does not have to be the same as the one in which you made the selec- 
tion, but the selection does have to be in a tty subwindow. 

Flush Input 

This item does not always appear in the menu. Occasonally the input buffer fills up and the termi- 
nal emulator appears to freeze. If this happens to you, Flush Input will appear in the menu. 
Selecting it will clear the buffer and allow you to continue using the terminal emulator. 
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SEE ALSO 

suntools (1), gfxtool (1), cmdtool(l), defaultsedit(l), Windows and Window-Based Tools: Beginner's 
Guide 


FILES 

7. ttyswrc 

/usr/lib/ttyswrc 

/usr/bin/shelltool 

/usr/bin/suntools 

/usr/demo/* 

/ usr/src/s un/sun tool's hell tool .c 

BUGS 

This release has the following notable bugs: 

(1) Remote login to another machine should be done with a terminal emulator subwindow matching 
the standard terminal size for the remote machine (for example, 34 by 80 characters for a Sun 
workstation). The remote machine does not understand terminals with non-standard size. 

(2) If more than 256 characters are input to a terminal emulator subwindow without an intervening 
newline, the terminal emulator may hang. If this occurs, display the tty subwindow menu; it con- 
tains the item, "Flush input", that you can invoke to correct the problem. ' 
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NAME 

size - size of an object file 

SYNOPSIS 

size [ object-file . . . ] 

DESCRIPTION 

Size prints the (decimal) number of bytes required by the text, data, and bss portions, and their sum in hex 
and decimal, of each object-file argument. If no file is specified, a.out is used. 

SEE ALSO 

a.out(5) 
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NAME 

sleep - suspend execution for an interval 

SYNOPSIS 

sleep time 

DESCRIPTION 

Sleep suspends execution for time seconds. It is used to execute a command after a certain amount of time 
as in: 

(sleep 105; command)& 

or to execute a command every so often, as in: 

while true 
do 

command 
sleep 37 

done 

SEE ALSO 

sleep(3) 

BUGS 

Time must be less than 2,147,483,647 seconds. 
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NAME 

soelim - eliminate .so’ s from nroff input 

SYNOPSIS 

soelim [ file . . . ] 

DESCRIPTION 

Soelim reads the specified files or the standard input and performs the textual inclusion implied by the nroff 
directives of the form 

.so somefile 

when they appear at the beginning of input lines. This is useful since programs such as tbl do not normally 
do this; it allows the placement of individual tables in separate files to be run as a part of a large document. 

An argument consisting of a single minus (-) is taken to be a file name corresponding to the standard input. 

Note that inclusion can be suppressed by using ‘ ' ’ instead of ‘ that is, 

'so /usr/lib/tmac.s 

EXAMPLE 

A sample usage of soelim would be 

soelim exum?.n | tbl | nroff -ms | col | lpr 

SEE ALSO 

colcrt(l), more(l) 
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NAME 

sort — sort or merge files 

SYNOPSIS 

sort [ +posl ] [ -pos2 ] [ -b ] [ -c ] [ -d ] [ -f ] [ -i ] [ -m ] [ -n ] [ -o name ] [ -r ] [ -tx ] 

[ -T dir ] [ -u ] filename . . . 

DESCRIPTION 

sort sorts and merges lines the named files, and writes the result on the standard output. The name *-’ 
means the standard input. If no input file ’s are named, the standard input is sorted. 

The default sort key is an entire line. Default ordering is lexicographic by bytes in machine collating 
sequence. 

When there are multiple sort keys, later keys are compared only after all earlier keys compare equal. Lines 
that otherwise compare equal are ordered with all bytes significant. 

OPTIONS 

+posl -pos2 

restricts a sort key to a field beginning at posl and ending just before pos2. posl and pos2 each 
have the form mm, optionally followed by one or more of the flags bdfinr, where m is the number 
of fields to skip from the beginning of the line and n tells a number of characters to skip further. 

If other options are present that affect the global ordering, they override any flags for this key. If 
the b option is in effect n is counted from the first nonblank in the field; b is attached indepen- 
dendy to pos2 . A missing .n means .0; a missing -pos2 means the end of the line. Under the -tx 
option, fields are strings separated by x; otherwise fields are nonempty nonblank strings separated 
by blanks. 

-b Ignore leading blanks (spaces and tabs) in field comparisons. 

-c Check that the input file is sorted according to the ordering rules; give no output unless the file is 

out of sort. 

-d ‘Dictionary’ order: only letters, digits and blanks are significant in comparisons. 

-f Fold upper case letters onto lower case. 

-i Ignore characters outside the ASCII range 040-0176 in nonnumeric comparisons. 

-m Merge only, the input files are already sorted. 

-n An initial numeric string, consisting of optional blanks, optional minus sign, and zero or more 
digits with optional decimal point, is sorted by arithmetic value. Option n implies option b. 

o name name is the name of an output file to use instead of the standard output This file may be the same 

as one of the inputs. 

-r Reverse the sense of comparisons. 

-tx ‘Tab character’ separating fields is x. 

T dir dir argument is the name of a directory in which temporary files should be made. 

— u Suppress all but one in each set of equal lines. Ignored bytes and bytes outside keys do not parti- 

cipate in this comparison. 

EXAMPLES 

Print in alphabetical order all the unique spellings in a list of words. Capitalized words differ from uncapi- 
talized. 

sort -u +0f +0 list 

Print the password file (passwd( 5)) sorted by user id number (the 3rd colon-separated field). 


Sun Release 3.0 


Last change: 8 August 1983 


309 



SORT ( 1 ) 


USER COMMANDS 


SORT ( 1 ) 


sort -t: +2n /etc/passwd 

Print the first instance of each month in an already sorted file of (month day) entries. The options -um 
with just one input file make the choice of a unique representative from a set of equal lines predictable. 

sort -um +0-1 dates 

FILES 

/usr/tmp/stm*, /tmp/* first and second tries for temporary files 
SEE ALSO 

uniq(l), comm(l), rev(l), join(l) 

DIAGNOSTICS 

Comments and exits with nonzero status for various trouble conditions and for disorder discovered under 
option -c. 

BUGS 

Very long lines are silendy truncated. 
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NAME 

sortbib - sort bibliographic database 
SYNOPSIS 

sortbib [-sKEYS] database ... 

DESCRIPTION 

Sortbib sorts files of records containing refer key-letters by user-specified keys. Records may be separated 
by blank lines, or by .[ and .] delimiters, but the two styles may not be mixed together. This program reads 
through each database and pulls out key fields, which are sorted separately. The sorted key fields contain 
the file pointer, byte offset, and length of corresponding records. These records are delivered using disk 
seeks and reads, so sortbib may not be used in a pipeline to read standard input. 

By default, sortbib alphabetizes by the first %A and the %D fields, which contain the senior author and 
date. The -s option is used to specify new KEYS. For instance, -sATD will sort by author, title, and date, 
while -sA+D will sort by all authors, and date. Sort keys past the fourth are not meaningful. No more than 
16 databases may be sorted together at one time. Records longer than 4096 characters will be truncated. 

Sortbib sorts on the last word on the %A line, which is assumed to be the author’s last name. A word in the 
final position, such as “jr.” or “ed.”, will be ignored if the name beforehand ends with a comma. Authors 
with two-word last names or unusual constructions can be sorted correctly by using the nrojf convention 
“\0” in place of a blank. A %Q field is considered to be the same as %A, except sorting begins with the 
first, not the last, word. Sortbib sorts on the last word of the %D line, usually the year. It also ignores lead- 
ing articles (like “A” or “The”) when sorting by titles in the %T or %J fields; it will ignore articles of any 
modem European language. If a sort-significant field is absent from a record, sortbib places that record 
before other records containing that field. 

SEE ALSO 

"refer" in Formatting Documents on the Sun Workstation 
refer(l), addbib(l), roffbib(l), indxbib(l), lookbib(l) 

BUGS 

Records with missing author fields should probably be sorted by title. 
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NAME 

spell, spellin, spellout - find spelling errors 
SYNOPSIS 

spell [ -v ] [ -b ] [ -d hlist ] [ -s hstop ] [ -h spellhist ] [ file ] ... 
spellin [ list ] 
spellout [ -d ] list 
DESCRIPTION 

Spell collects words from the named documents, and looks them up in a spelling list. Words that neither 
occur among nor are derivable (by applying certain inflections, prefixes or suffixes) from words in the spel- 
ling list are printed on the standard output. If no files are named, words are collected from the standard 
input. 

Spell ignores most troff(l), tbl(l), and eqn(Y) constructions. 

The spelling list is based on many sources, and while more haphazard than an ordinary dictionary, is also 
more effective in respect to proper names and popular technical words. Coverage of the specialized voca- 
bularies of biology, medicine and chemistry is light. 

Pertinent auxiliary files may be specified by name arguments, indicated below with their default settings. 
Copies of all output are accumulated in the history file. The stop list filters out misspellings (for example, 
thier=thy-y+ier) that would otherwise pass. 

Two routines help maintain the hash lists used by spell. Both expect a list of words, one per line, from the 
standard input Spellin adds the words on the standard input to the preexisting list and places a new list on 
the standard output If no list is specified, the new list is created from scratch. Spellout looks up each word 
in the standard input and prints on the standard output those that are missing from (or present on, with 
option -d) the hash list. 

OPTIONS 

-v Print all words not literally in the spelling list as well as plausible derivations from spelling list 
words. 

-b Check British spelling. Besides preferring centre, colour, speciality, travelled, and so on, the -b 
option insists upon -ise in words like standardise, Fowler and the OED to the contrary notwith- 
standing. 

-x print every plausible stem with *=’ for each word. 

FILES 

/usr/dict/hlist[ab] hashed spelling lists, American & British 
/usr/dict/hstop hashed stop list 

/usr/dict/spellhist history file 
/usr/dict/words list of words 

/usr/lib/spell 

SEE ALSO 

deroff(l), sort(l), tee(l), sed(l) 

BUGS 

The spelling list’s coverage is uneven; new installations will probably wish to monitor the output for 
several months to gather local additions. 

British spelling was done by an American. 
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NAME 

spline - interpolate smooth curve 
SYNOPSIS 

spline [ -a ] [ -k ] [ — n ] [ — p ] [ — x ] 

DESCRIPTION 

Spline takes pairs of numbers from the standard input as abcissas and ordinates of a function. It produces a 
similar set, which is approximately equally spaced and includes the input set, on the standard output. The 
cubic spline output (R. W. Hamming, Numerical Methods for Scientists and Engineers, 2nd ed., 349ff) has 
two continuous derivatives, and sufficiently many points to look smooth when plotted, for example by 
graphs 1G). 

OPTIONS 

-a Supply abscissas automatically (they are missing from the input); spacing is given by the next argu- 
ment, or is assumed to be 1 if next argument is not a number. 

-k The constant k used in the boundary value computation 

y'6 = W. y'n = ¥n-i 
is set by the next argument. By default k = 0. 

-n Space output points so that approximately n intervals occur between the lower and upper x limits. 
(Default n = 100.) 

-p Make output periodic, that is, match derivatives at ends. First and last input values should normally 
agree. 

-x Next 1 (or 2) arguments are lower (and upper) x limits. Normally these limits are calculated from the 
data. Automatic abcissas start at lower limit (default 0). 

SEE ALSO 

graph(lG) 

DIAGNOSTICS 

When data is not strictly monotonic in x, spline reproduces the input without interpolating extra points. 

BUGS 

A limit of 1000 input points is enforced silently. 
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NAME 

split - split a file into pieces 
SYNOPSIS 

split [ —number ] [ infile [ outfile ] ] 

DESCRIPTION 

split reads file and writes it in n-line pieces (default 1000) onto a set of output files (as many files as neces- 
sary). The name of the first output file is outfile with aa appended, the second file is outfile ah, and so on 
lexicographically. 

If no outfile is given, x is used as default (output files will be called xaa,xab, etc.). 

If no infile is given, or if - is given in its stead, then the standard input file is used. 

OPTIONS 

-number Number of lines in each piece. 
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NAME 

strings - find printable strings in an object, or other binary, file 
SYNOPSIS 

strings [ - ] [ -o ] [ -number ] file . . . 

DESCRIPTION 

Strings looks for ascii strings in a binary file. A string is any sequence of 4 or more printing characters 
ending with a newline or a null. 

Strings is useful for identifying random object files and many other things. 

OPTIONS 

Look everywhere in the file for strings. If this flag is omitted, strings only looks in the initialized 
data space of object files. 

-o Precede each string by its offset in the file (in octal). 

—number 

Use number as the minimum string length rather than 4. 

SEE ALSO 

od(l) 

BUGS 

The algorithm for identifying strings is extremely primitive. 
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NAME 

strip - remove symbols and relocation bits 

SYNOPSIS 

strip name . . . 

DESCRIPTION 

Strip removes the symbol table and relocation bits ordinarily attached to the output of the assembler and 
linker. This is useful to save space after a program has been debugged. 

The effect of strip is the same as use of the -s option of Id. 

FILES 

/tmp/stm? temporary file 

SEE ALSO 

ld(l) 
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NAME 

stty - set terminal options 
SYNOPSIS 

stty [ option ... ] 

DESCRIPTION 

Stty sets certain I/O options on the current output terminal, and directs its output to the diagnostic output. 
With no argument, it reports the speed of the terminal and the settings of options which are different from 
their defaults. With the argument “all”, all normally-used option settings are reported. With the argument 
everything ’ ’ , everything stty knows about is printed. 

OPTIONS 

Options to stty are selected from the following set; 

even allow even parity input 

-even disallow even parity input 

odd allow odd parity input 

-odd disallow odd parity input 

raw raw mode input (no input processing (erase, kill, interrupt, ...); parity bit passed back) 

-raw negate raw mode 

cooked same as ‘-raw’ 

cbreak make each character available to read(2 ) as received; no erase and kill processing, but all 
other processing (interrupt, suspend, ...) is performed 
-cbreak make characters available to read only when newline is received 
— nl allow carnage return for new-line, and output CR-LF for carriage return or new-line 

nl accept only new-line to end lines 

echo echo back every character typed 

-echo do not echo characters 

lease map upper case to lower case 

-lease do not map case 

tandem enable flow control, so that the system sends out the stop character when its internal queue is 
in danger of overflowing on input, and sends the start character when it is ready to accept 
further input 

—tandem disable flow control 

-tabs replace tabs by spaces when printing 

tabs preserve tabs 

ek set erase and kill characters to A H (control-H) and 'U 

For the following commands which take a character argument c, you may also specify c as the “u” or 
undef , to set the value to be undefined. A value of “*x”, a 2 character sequence, is also interpreted as a 
control character, with “ A ?” representing delete. 

erase c set erase character to c (default lA ?’). 
kill c set kill character to c (default ,A U’). 
intr c set interrupt character to c (default ,A C’). 
quit c set quit character to c (default ,A \’). 

start c set start character to c (default ‘ A Q’). 

stop c set stop character to c (default ,A S’). 

eof c set end of file character to c (default ,A D’). 

brk c set break character to c (default undefined.) This character is an extra wakeup causing charac- 
ter. 

crO crl cr2 cr3 

select style of delay for carriage return (see ioctl( 2)) 
r.10 nil nl2 nI3 

select style of delay for linefeed 
tabO tabl tab2 tab3 

select style of delay for tab 


Sun Release 3.0 


Last change: 19 March 1984 


317 



STTY(l) 


USER COMMANDS 


STTY(l) 


ffO ffl select style of delay for form feed 
bsO bsl select style of delay for backspace 

tty33 set all modes suitable for the Teletype Corporation Model 33 terminal. 

tty37 set all modes suitable for the Teletype Corporation Model 37 terminal. 

vt05 set all modes suitable for Digital Equipment Corp. VT05 terminal 

dec set all modes suitable for Digital Equipment Corp. operating systems users; (erase, kill, and 

interrupt characters to '?, 'U, and 'C, decctlq and “newcrt”.) 

tn300 set all modes suitable for a General Electric TermiNet 300 

ti700 set all modes suitable for Texas Instruments 700 series terminal 

tek set all modes suitable for Tektronix 4014 terminal 

0 hang up phone line immediately 

50 75 110 134 150 200 300 600 1200 1800 2400 4800 9600 19200 exta extb 

Set terminal baud rate to the number given, if possible. (These are the speeds supported by the 
DH-11 interface). 

The driver which supports the job control processing of csh( 1) is fully described in tty (A). The options in 
the list below can only be selected by using the new option to stfy(l)- 


new Use new driver (switching flushes typeahead). 

crt Set options for a CRT (crtbs, ctlecho and, if >= 1200 baud, crterase and crtkill.) 

crtbs Echo backspaces on erase characters. 

prterase For printing terminal echo erased characters backwards within “\” and 
crterase Wipe out erased characters with “backspace-space-backspace.” 

-crterase Leave erased characters visible; just backspace, 
crtkill Wipe out input on like kill ala crterase. 

-crtkill Just echo line kill character and a newline on line kill. 

ctlecho Echo control characters as “V (and delete as “'?”.) Print two backspaces following the 

EOT character (default “D’). 

-ctlecho Control characters echo as themselves; in cooked mode EOT (default “D’) is not echoed. 


decctlq 

-decctlq 

tostop 

-tostop 

tilde 

-tilde 

flusho 

-flusho 

pendin 

-pendin 

intrup 

-intrup 

mdmbuf 

-mdmbuf 

litout 

-litout 

nohang 

-nohang 

etxack 


After output is suspended (normally by A S), only a start character (normally 'Q) will restart it. 
This is compatible with DEC’S vendor supplied systems. 

After output is suspended, any character typed will restart it; the start character will restart out- 
put without providing any input (This is the default.) 

Background jobs stop if they attempt terminal output. 

Output from background jobs to the terminal is allowed. 

Convert to on output (for Hazeltine terminals). 

Leave poor alone. 

Output is being discarded usually because user hit “O’ (internal state bit). 

Output is not being discarded. 

Input is pending after a switch from cbreak to cooked and will be re-input when a read 
becomes pending or more input arrives (internal state bit). 

Input is not pending. 

Send a signal (SIGTINT) to the terminal control process group whenever an input record (line 
in cooked mode, character in cbreak or raw mode) is available for reading. 

Don’t send input available interrupts. 

Start/stop output on carrier transitions (not implemented). 

Return error if write attempted after carrier drops. 

Send output characters without any processing. 

Do normal output processing, inserting delays, etc. 

Don’t send hangup signal if carrier drops. 

Send hangup signal to control process group when carrier drops. 

Diablo style etx/ack handshaking (not implemented). 
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The following special characters are applicable only to the new teletype driver and are not normally 
changed. J 

susp c set suspend process character to c (default “Z’). 

dsusp c set delayed suspend process character to c (default ,A Y’). 

rprnt c set reprint line character to c (default “R’). 

flush c set flush output character to c (default ,A 0’). 
werase c set word erase character to c (default tA W’). 

Inext c set literal next character to c (default ,A V’). 

SEE ALSO 

tset(l), tty(4) 
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NAME 

stty_from_defaults - set “editing characters” from defaults database 

SYNOPSIS 

stty_from_defaults 

DESCRIPTION 

stty Jrom_defaults is a utility provided with the SunView environment. 

stty Jrom._defau.lts sets the three editing characters (to erase a character, erase a word, and kill a line) 
according to the choices in your defaults database. It does not set any other tty options. If you run ,«ry(l) 
in your .login or rc.local files, you may want to run sttyJrom_defaults immediately after it. This will over- 
ride any settings of stty erase, stty werase, or stty kill, so that you will have the same character-editing 
behavior with SunView applications and other Unix programs. 

To specify the editing characters sttyJr.om_defaults will set, run defaultsedit{ 1) and select the “Text” 
category. The editing characters are called Edit_back_char, Edit_back_word, and Edit_back_line. Type 
the value you want to the right of each item. To specify ctrl-X, type ‘ YX” — that is, the three characters 
V, and ‘X’. To specify DEL, type “\T\ 

If you do not specify your own values, the default values are DEL, CTRL-W, and CTRL-U, respectively. 
SEE ALSO 

defaultsedit( 1), s«y(l), suntools(l) 

Windows and Window-Based Tools: Beginner’s Guide 
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NAME 

su - substitute user id temporarily 
SYNOPSIS 

su [ username ] [ - ] [ -c command ] [ -f ] 

DESCRIPTION 

Su changes your login to that of the specified username. Su asks for the password, just as if you were log- 
ging in as username, and, if the password is given, changes to that username and invokes the shell 
specified in the password file for that username, without changing the current directory. The user environ- 
ment is thus unchanged except for HOME and SHELL, which are taken from the password file for the user 
being substituted (see environ (5)). The new user ID stays in force until the shell exits. 

If no username is specified, ‘root’ is assumed. To remind the super-user of his responsibilities, the Shell 
substitutes ‘#’ for its usual prompt. 

OPTIONS 

The - flag performs a complete login. That is, it moves to the home directory, reads the .login file, 
and reads the .cshrc file for the new user-ID to configure the new shell. 

— c command 

execute command after logging in as the new user. 

-f Perform a fast login. That is, do not change directories, do not read the .cshrc file, and do not read 
the .login file for the new user ID to configure the new shell. 

If the - and -f flags are omitted, only the .cshrc file for the new user-ID is used to configure the new shell. 
SEE ALSO 

sh(l), csh(l) 
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NAME 

sum - sum and count blocks in a file 

SYNOPSIS 

sum file 

DESCRIPTION 

Sum calculates and displays a 16-bit checksum for the named file, and also displays the size of the file in 
kilobytes. It is typically used to look for bad spots, or to validate a file communicated over some transmis- 
sion line. 

SEE ALSO 

wc(l) 

DIAGNOSTICS 

‘Read error’ is indistinguishable from end of file on most devices; check the block count. 
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NAME 

sun - is current machine a Sun Workstation 
SYNOPSIS 


if sun; then fi 

(sh) 

if { sun } then 

(csh) 

endif 



DESCRIPTION 

The sun command is, on Sun Workstations, the same as true( 1); on VAX’es and other machines it is the 
same as false (1). 

SEE ALSO 

false(l), true(l), vax(l) 
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NAME 

suntools - Run the SunView environment 
SYNOPSIS 

suntools [ — n | — s startup file ] [ -d display device ] [ -m mouse device ] 

[ -k keyboard device ] [ -b red green blue ] [ -f red green blue ][—!][ — p ][— [B|F|P]] 

GETTING STARTED 

suntools starts up the SunView environment and (unless you have specified otherwise) a default arrange- 
ment of a few useful “tools,” or window-based utilities. 

See Start-up Processing below to learn how to specify your own initial arrangement of tools. Some of the 
behavior of suntools is controlled by settings in your defaults database; see SunView Defaults below. 

OPTIONS 

-n Bypass startup processing by ignoring both the lusrllibl suntools and '/suntools files. See Startup 
Processing for details. 

— s startup file 

Read startup commands firom startup file (instead of lusrllibl suntools or '/suntools). 

— d display device 

Use display device as the output device on which to run, rather than the default frame buffer dev- 
ice, Idevlfb. 

m mouse device 

Use mouse device as the system pointing device (locator), rather than the default mouse device, 
Idevlmouse. 

-k keyboard device 

Accept keyboard input from keyboard device, rather than the default keyboard device, Idev/kbd. 

-b red green blue 

Specifies the values of the red, green and blue components of the background color. If this option 
is not specified, each component of the background color is 255 (white). 

— f red green blue 

Specifies the values of the red, green and blue components of the foreground color. If this option 
is not specified, each component of the foreground color is 0 (black). 

-i Invert the background and foreground colors used on the screen. On a monochrome monitor, this 
option provides a video reversed image. On a color monitor, colors that are not used as the back- 
ground and foreground are not affected. 

-p Prints to standard out the name of the window device used for the suntools Root Window. 

-B Use the background color for the Root Window color. 

-F Use the foreground color for the Root Window color. 

-P Use a stipple pattern for the Root Window color. This option is assumed unless -F or -B is 
specified. 

DESCRIPTION 

Windows 

The SunView environment always has one window open, called the Root Window, which covers the whole 
screen. A solid color is its only content. Each tool is given its own window which lies on top of some of 
the Root Window (and possibly on top of other tools). A window obscures any part of another window 
which lies below it. 
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Input to Windows 

Mouse input is always directed to the window the mouse cursor is in. You can have keyboard input follow 
mouse input, or you can use the “Click-to-Type” approach. With Click-to-Type, keyboard input contin- 
ues to be directed to a window, no matter where the mouse is pointing, until you click the left or middle 
mouse button in another window. Click-to-Type is an option in your defaults database; see SunView 
Defaults below. If you are not using Click-to-Type, and your mouse cursor is in the Root Window, key- 
board input is discarded. 

Your input actions (mouse motions, button pushes, and keystrokes) are synchronized. This means that you 
can “type-ahead” and “mouse-ahead,” even across windows. 

The Mouse Buttons 

Left button (the select button) Click once to select or choose objects. 

Middle button (the adjust button) Click once to shorten or lengthen your selection. 

Right button (the menu button) Depress and hold down to invoke menus. 

Menus 

suntools provides pop-up menus. In the current release, there are two styles of pop-up menus: the original 
menu style, called stacking menus, and a new style, called walking menus (also known as “pull-right 
menus”). A menu is invoked by pressing and holding the menu button. The menu remains on the screen 
as long as you hold the menu button down. To select a menu item, point at it (it will be highlighted), then 
release the menu button. 

With stacking menus, more than one menu can appear simultaneously. The menus are shown in a stack, 
with the label of each menu visible, and with the current menu on top so that its items are visible. To bring 
a menu to the top (and make its items available), select its label as you would a menu item. Then push the 
menu button again. The menu stack is repainted with the selected menu on top. 

With walking menus, any menu item can have an arrow (.=> ) on the right. Pointing to this arrow invokes 
a sub-menu, with additional menu items that can be selected. Selecting an item that has an arrow (a 
“pull-right item”) invokes the first item on the sub-menu. 

Walking menus are an option in your defaults database; see SunView Defaults below. 

The Root Window Menu 

You can use the default Root Window Menu to start ten common tools and perform three functions. To 
invoke it, hold down the menu button when the mouse cursor is anywhere in the Root Window. 

The items in the default Root Window Menu are: 

ShellTool Creates a new shelltool( 1), running a new copy of the shell. 

CommandTool Creates a new cmdtool(l), a scrollable cousin of the shelltool. 

MailTool Creates a new mailtoolfl). 

TextEditor Creates a new textedit(l). 

DefaultsEditor Creates a new defaultsedit(l), for browsing or changing your defaults database. 
IconEditor Creates a new iconedit(l). 

DbxTool Creates a new dbxtool( 1), a window-based debugger. 

PerfMeter Creates a new perfmeter( 1), to monitor system performance. 

GraphicsTool Creates a new gfxtool(\), for running graphics programs. 

Console Creates a new Console window, a cmdtool with a -C flag, which acts as the system 
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console. In particular, most error messages will be directed to the console. You should 
always have a console window on your screen. 

Lock Screen Completely covers the screen with a graphics display, and “locks” the workstation until 
you type your password. When you “unlock” the workstation, the screen is restored as 
it was when you locked it See lockscreen( 1) for details. 

Redisplay All Redraws all the contents of the screen. Use this to repair damage done by processes that 
wrote to the screen without consulting the SunView system. 

Exit Suntools Exits the suntools program. Closes all tool windows and kills their associated processes 
(depending on the processes, this can be fairly slow). You return to the shell which 
invoked suntools. 

This command requires confirmation: When it prompts you, press the left mouse button 
to complete the Exit Suntools command; press the right button to cancel. 

You can specify your own Root Window Menu; see SunView Defaults below. 

The Frame Menu 

A small set of universal functions are available through the Frame Menu. There are also accelerators for 
some of these functions; see below. 

You can invoke the Frame Menu when the cursor is over any part of the tool which does not provide an 
application-specific menu, such as the tool namestripe (black stripe holding the tool’s name), the border 
stripes of the window, and the whole of the tool’s icon. 

The items in the Frame Menu are: 

Only one of Close or Open appears in the menu, depending on the current state of the 
window. Close shrinks the tool to a small image (an icon). Open reopens an icon and 
places the tool in the spot it occupied when it was open. 

Icons are placed on the screen according to the icon policy in your defaults database; see 
SunView Defaults below. You can move a closed window just like an open window. 
When the window is closed, the tool’s process(es) continue to run. 

Moves the tool window to another spot on the screen. When invoked. Move instructs 
you with an instruction box that appears in the middle of the screen. 

If you are using walking menus, Move has a sub-menu with two items: Constrained 
and Unconstrained. Constrained moves are either vertical or horizontal, but not both. 
Selecting Move invokes a Constrained move. 

Shrinks or stretches the size of a window on the screen. Resize, like Move, instructs 
you with an instruction box that appears in the middle of the screen. 

If you are using walking menus, Resize has a sub-menu with four items: Constrained, 
Unconstrained, Zoom (or UnZoom, depending on the current state of the window) and 
FuIIScreen. Constrained resizes are either vertical or horizontal, but not both. Zoom 
makes a window the full height of the screen; UnZoom undoes this. FuIIScreen makes 
a window the full height and width of the screen; UnZoom undoes this. Selecting 
Resize invokes a Constrained resize. 

Brings the window to ‘the top of the pile’. The whole window becomes visible, and 
occludes any window it happens to overlap on the screen. 

Puts the window on the ‘bottom of the pile’. The window is occluded by any window 
which overlaps it 

Redraws the contents of the window. 

Notifies the tool to terminate gracefully. This command requires the same type of 
confirmation as the Exit Suntools command in the Root Window Menu. 


Expose 

Hide 

Redisplay 

Quit 


Close (Open) 


Move 


Resize 
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Frame Menu Accelerators 

Accelerators are provided for some of the Frame Menu functions. You can invoke these functions quickly 
with a simple button push in the tool window’s name stripe or outer boundary, without displaying a menu. 
See Windows and Window-Based Tools: Beginner’ s Guide for more details. 

The accelerators for the various functions are: 

Open Click the select mouse button when the cursor is over the icon. 

Move Depress the adjust mouse button while the cursor is in the tool’s name stripe or outer 

boundary. A bounding box is displayed which tracks the mouse as long as you hold the 
adjust button down. 

If the cursor is near a comer when you press the mouse button, the move is Uncon- 
strained. If it is in the middle third of a side, the move is Constrained. 

Resize While holding down the CTRL key, depress the adjust mouse button while the cursor is in 

the tool’s name stripe or outer boundary. A bounding box is displayed, one side or 
comer of which tracks the mouse as long as you hold the adjust button down. 

If the cursor is near a comer when you press the mouse button, the resize is Uncon- 
strained. If it is in the middle third of a side, the resize is Constrained. 

Zoom (UnZoom) While holding down the CTRL key, click the select mouse button while the cursor is in 
the tool’s name stripe or outer boundary. 

Expose Click the select mouse button while the cursor is on the tool’s name stripe or outer boun- 

dary. 

Hide While holding down the shift key, click the select mouse button while the cursor is on 

the tool’s name stripe or outer boundary. 

In addition, you can use two function keys as even faster accelerators. To expose a window that is partially 
hidden, hit the Expose key (normally L5) while the cursor is anywhere in the tool window, not just on the 
tool’s name stripe or outer boundary. Or, if the window is completely exposed, use the Expose key to hide 
it Similarly, to close an open window, hit the Open key (normally L7) while the cursor is anywhere in the 
tool window, not just on the tool’s name stripe or outer boundary. Or, if the window is iconic, use the 
Open key to open it You can change which keys mean Expose and Open by using setkeys( 1). 

In many multi-subwindow tools, you can adjust the boundary between two subwindows up or down 
without changing the overall size of the tool. While holding down the CTRL key, depress the adjust mouse 
button over the boundary. A bounding box is displayed for the subwindow selected. Adjust the size of that 
subwindow, exactly as with the Resize operation. 


Start-up Processing: The ‘.sun tools’ File 

Unless you override it, suntools will start up with a predefined arrangement of windows. The default 
arrangement is specified by the file lusr/lib/suntools. If there is a file called suntools in your home direc- 
tory, that will be used instead. The -s flag on the command line indicates that the initial window arrange- 
ment should be read from a file with a different name. The -n switch suppresses this start-up processing 
altogether. 

To create your own suntools, arrange the screen the way you like, then save the arrangement by running 
toolplaces and redirecting its standard output to .suntools. See toolplaces( 1) for a description of the format 
of this file, or take a look at lusr/lib/suntools. 

Sun View Defaults 

SunView allows you to customize the behavior of tools and packages by setting options in a defaults data- 
base (one for each user). Use defaultsedit(l) to browse and edit your defaults database. Select the “Sun- 
View” category to see the following items: 
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If enabled, the Root Window Menu, the Frame Manager Menu, and many tools will use 
walking menus. Tools that have not been converted will still use stacking menus. If dis- 
abled, all tools will use stacking menus. Default value is “Disabled”. 

If enabled, keyboard input will stay in a window until you click the left or middle mouse 
button in another window. If disabled, keyboard input will follow the mouse. Default 
value is “Disabled”. 

You can change the SunView default font by giving the full pathname of the font you 
want to use. Some alternate fonts are in the directory lusrlliblfontslfixedwidthfonts. The 
previous (2.0 release) default font is lusrlliblfontslfixedwidthfontslscreen.r.13. Default 
value is null, which gives you the same effect as if you had specified 
lusrlliblfontslfixedwidthfontslscreen.r.ll . 

Rootmenufilename 

You can change the Root Window Menu by giving the full pathname of a file that 
specifies your own menu. See Customizing the Root Window Menu below for details. 
Default value is null, which gives you the menu found in lusr/lib/rootmenu. 

Icon_gravity Determines which edge of the screen (“North”, “South”, “East”, or “West”) icons 
will place themselves against Default value is “North”. 

Icon close level Determines whether icons will close ahead of or behind other windows and icons. 
Default value is “Ahead of all”. 

Jump_cursor_on_resize 

If enabled, during a resize the cursor will jump to the edge of the window. If disabled, 
the window edge will move to the current location of the cursor. Default value is “Dis- 
abled”. 

Audible_bell If enabled, the “bell” command will result in a beep. Default value is “Enabled”. 

Visible_bell If enabled, the “bell” command will cause the screen to flash. Default value is 
“Enabled”. 

Ttysubwindow/Retained 

If enabled, interactive performance of shelltool and gfxtool will be improved, although at 
a slight expense of memory usage. Default value is “No”, meaning disabled. 

After you have set the options you want, click on the Save button in defaultsedir, then exit suntools and res- 
tart it. 

Customizing the Root Window Menu 

The file called lusr/lib/rootmenu contains the specification of the default Root Window Menu. You can 
change the Root Window Menu by creating your own file and giving its name in the Rootmenu_filename 
item in the SunView Defaults (see above). 

Lines in the file have the following format: The left side is a menu item to be displayed; the right side is a 
command to be executed when that menu item is invoked. You can also include comment lines (beginning 
with a “#’) and blank lines. 

If you are using stacking menus (“Walking_menus Disabled” in SunView defaults), the menu item must 
be a string (strings with embedded blanks must be delimited by double quotes). If you are using walking 
menus (“Walking_menus Enabled”), the menu item can be a string or the full pathname of an icon file, 
delimited by angle brackets. With care, strings and icons can be mixed in one menu. 

There are four reserved-word commands that can appear on the right side. 

EXIT Exit the suntools program, after user confirmation. 

REFRESH Redraw the entire screen. 


Walkingjnenus 

Click_to_Type 


Font 
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MENU If you are using stacking menus, a menu is added to the pile with the Root Window 

Menu. The menu contents are taken from the filename that follows the MENU com- 
mand. You must give the full pathname of the file. 

If you are using walking menus, this menu item is a pull-right item with a submenu. If a 
filename follows the MENU command, the submenu contents are taken from the 
filename. Otherwise, all the lines between this MENU command and a matching END 
command are added to the submenu. 

END Marks the end of a nested submenu. The left side of this line should match the left side 

of a line with a MENU command. Not valid if you are using stacking menus. 

If the command is not one of these four reserved-word commands, it is treated as a command line and exe- 
cuted. No shell interpretation is done, although you can run a shell as a command. 

Here is a menu file that demonstrates some of these features: 

Quit EXIT 

Clock clock -r -f 

"Mail reader" mailtool 

"More tools” MENU /usr/ourhost/jdoe/moretools.menu 
"Click to type" swin -c 
"Follow mouse" swin -m 

Snapshot sh -c "screendump | rastrepl | lpr -v -Pversatec" 

# Only if you are using walking menus: 

"Nested menu" MENU 

Cmdtool cmdtool 

Shelltool shelltool 

"Nested menu" END 
"Icon menu" MENU 

</usr/include/images/textedit.icon> textedit 
</usr/include/images/iconedit.icon> iconedit 
"Icon menu" END 

Multiple/Color Displays 

The suntools program runs on either a monochrome or color screen. Each screen on a machine may have 
its own invocation of suntools running on it The keyboard and mouse input devices are shared among 
multiple screens. The mouse cursor slides from one screen to another when you move the cursor off the 
edge of a screen. 

A common multiple display configuration is one monochrome and one color screen. You could set up an 
instance of suntools on each screen in the following way: 

1) Invoke suntools on the monochrome display by running “suntools”. This starts suntools on the 
default frame buffer named Idevlfb. 

2) In a shelltool, run “suntools -d /dev/cgoneO”. This starts suntools on a color screen named 
/dev/cgoneO. 

3) In a shelltool on the monochrome screen, run “adjacentscreens /dev/fb -r /dev/cgoneO”. This sets 
up cursor tracking so that the cursor slides from the monochrome screen to the color screen when 
you move the cursor off the right hand side of the monochrome screen, and back when you move 
the cursor off the left hand side of the color screen. 
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Generic Tool Arguments 

Most window-based applications now take the following arguments in their command lines: 


FLAG (LONG FLAG) 

ARGS 

NOTES 

-Ww 

(-width) 

columns 


-Wh 

(-height) 

lines 


-Ws 

(-size) 

xy 

x and y are in pixels 

-Wp 

(-position) 

xy 

x and y are in pixels 

-WP 

(-icon_position) 

xy 

x and y are in pixels 

-W1 

(-label) 

"string" 


-Wo 

(-open) 


makes the tool start open 

-Wc 

(-closed) 


makes the tool start closed (iconic) 

-Wi 

(-iconic) 


same as -closed 

-Wt 

(-font) 

filename 


-Wf 

(-foreground_color) 

red green blue 

0-255 (no color-full color) 

-Wb 

(-backgroundcolor) 

red green blue 

0-255 (no color-full color) 

-Wg 

(-set_default_color) 


(apply color to subwindows too) 

-WI 

(-iconimage) 

filename 

(for tools with non-default icons) 

-WL 

(-icon_label) 

"string" 

(for tools with non-default icons) 

-WT 

(-icon_font) 

filename 

(for tools with non-default icons) 

-WH 

(-help) 


print this table 

Each 

flag option may be specified 

in either its short form or its long form; the two are completely 


synonymous. 

Getting Out 

To exit any tool, invoke the Quit command in the Frame Menu as described above. To exit the entire win- 
dow system, invoke Exit Suntools in the Root Window Menu as described above. Make sure that all win- 
dows are in a safe condition (for example, editors have written out all changes) first 

You can exit suntools via the keyboard by typing 'D followed by 'Q. There is no confirmation. This facil- 
ity provides an escape if you inadvertently start suntools without a mouse attached to the system. 

SEE ALSO 

Windows and Window-Based Tools: Beginner’s Guide 
Some of the applications that run in the SunView environment: 

clock(l), cmdtooHY), dbxtool{\), defaultsedit{\), fontedit{\), gfxtool(l), iconedit{l), lockscreen(l), mail- 
tool (1), overview^ 1), perf meter (1), perfmon{\), shelltool{ 1), tektooHl), textedit(l), traffic(\) 

Some of the utility programs that run in or with the SunView environment: 

adjacentscreens(T), clear Junctions (1), get_selection(l), rastps(l), setkeys(l), sttyJrom_defaults(\), 
svvm(l), toolplaces( 1) 

Some demonstration programs: 

/usr/demo/* 


FILES 

"/.suntools 

/usr/lib/suntools 

/usr/lib/rootmenu 

/usr/lib/fonts/fixedwidthfonts/* 

/dev/winx 

/dev/ptypx 

/dev/ttypx 
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/dev/{fb, kbd, mouse} 

/etc/utmp 

BUGS 

This release has the following notable bugs: 

(1) Messages from the kernel ignore window boundaries unless console messages have been 
redirected, thus trashing the display. Recover from this by invoking the Redisplay All item on the 
Root Window Menu. Then invoke the Console item to start a console. 

(2) To improve interactive performance, the kernel should be reconfigured in order to make more 
memory available for applications. See the System Manager’s Guide . 

(3) With an optical mouse, sometimes the arrow-shaped cursor will not move at start-up; moving the 
mouse in large circles on its special pad for a few seconds will bring the cursor to life. 

(4) S untools needs the file /etc/utmp to have read and write permission for all users. It should have 
been installed with these permissions, but if not, you need to use chmod to change the permis- 
sions. 

(5) On a color display, all of the colors may “go strange” when the cursor is in certain windows. 
This is caused by SunView accommodating a particular window’s request for a large number of 
colors. 
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NAME 

swin - set/get SunView user input options 
SYNOPSIS 

swin [ -c ] [ -g ] [ -h ] [ -m ] [ -r event value shift_state ] [ -s event value shift_state ] [ -t seconds ] 
DESCRIPTION 

The swin (set window; analogous to stty(l )) command lets you change some of the input behavior of your 
SunView environment. By default, your keyboard input follows your mouse cursor. This means that in 
order to type to a window you position the mouse cursor over the window. This is called keyboard- 
follows-mouse mode. 

You can specify that the keyboard input continues to go to the same window, regardless of the mouse cur- 
sor position, until you take some specific action, like clicking the mouse. When this is done, you can roam 
around the screen with the mouse cursor and not change the window to which keyboard input is directed. 
Running SunView like this is said to be operating in click-to-type mode. 

When running in click-to-type mode, one user action sets the type-in point in the window that you want to 
receive keyboard input. The default user action to do this is the pressing of the left mouse button while 
positioning the mouse cursor over the new type-in point This user action can be changed. 

Another user action restores the previous type-in point in the window that you want to receive keyboard 
input. The default user action to do this is the pressing of the middle mouse button while positioning the 
mouse cursor over the window. This user action can be changed. 

OPTIONS 

— c Turn on click-to-type mode using the default user actions: the left mouse button sets the type-in 
point and the middle button restores the type-in point. You can use the defaultsedit(l) program to 
set click-to-type on permanently; see the SunView/Click_to_Type option. 

-m Run in keyboard-follows-mouse mode. 

-s event value shift state 

Set the user action that sets the type-in point and sets the keyboard input window. The event 
identifies the particular user action and is one of: 

LOC_WINENTER 

the mouse cursor entering a window 

MS_LEFT 

the left mouse button 
MS_MIDDLE 

the middle mouse button 
MS_RIGHT 

the right mouse button 
decimal jiumber 

place the decimal number of a firm event here; see list of events in 
lusr/include/sundev/vuid_event.h (avoid function keys, normally unused control-ascii 
characters are OK, normally unused shift keys are OK). 

value identifies the transition of the event and is one of: 

ENTER the mouse cursor entering a window (use with LOC_WINENTER) 
down the button associated with event went down 
UP the button associated with event went up (avoid this) 

The shift _state identifies the state of the shift keys at the time of the event/value pair in order for 
that pair to be used to control the keyboard input window. The shift _state is one of: 

SHIFT_DONT_CARE 


332 


Last change: 24 December 1985 


Sun Release 3.0 



SWIN(l) 


USER COMMANDS 


SW1N(1) 


ignore the state of the shift keys 
SHIFT_ALL_UP 

all the shift keys must be up 
SHIFT_LEFT 

the left shift key must be down (not the key labelled LEFT) 

SHIFTJUGHT 

the right shift key must be down (not the key labelled right) 

SHIFT_LEFTCTRL 

the left control key must be down 
SHIFTRIGHTCTRL 

the right control key must be down 

-r event value shift _state 

Set the user action that restores the type-in point and sets the keyboard input window. This user 
action is swallowed so that the application that owns the window doesn’t see it. However, if the 
window already has keyboard input or if the window refuses keyboard input then this user’action 
is passed on through to the application. The parameters to this command are like for -s. The fol- 
lowing example shows modifying the default click-to-type user actions so that a left-shift is 
required for the restore user event: 

tutorial% swin -c -r ms_middle down shift_left 

— t seconds 

Sun View synchronizes input so that it doesn’t hand out the next user action until the application 
fielding the current user action finishes its processing. This allows type-ahead and mouse-ahead. 
If an application doesn t finish processing within a given length of time (process virtual time; not 
wall clock time), the next user action is handed out anyway. This avoids any one application from 
hanging the workstation. The -t command sets this time limit. A seconds value of 0 tells Sun- 
View to run unsynchronized; beware of race conditions in this mode. The default seconds value is 
2 and the -c command makes it 10 seconds. 

~ g Get the state of the user input options controlled by swin. If no arguments are supplied to swin 

then -g is implied. 

-h Print out a help message that briefly describes the options to swin. 

FILES 

/usr/include/ sundev/vuid_event.h - list of event codes 
SEE ALSO 

suntools(l), defaultsedit(l) 

Windows and Window-Based Tools: Beginner’ s Guide 
DIAGNOSTICS 

“swin not passed parent window in environment” - must be running suntools already; swin doesn’t work 

unless SunView is started already. 

BUGS 

swin gets you no help in preventing you from specifying -r or -s parameters that are not sensible. 
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NAME 

sync - update the super block 

SYNOPSIS 

sync 

DESCRIPTION 

sync forces any information on its way to the disk to be written out immediately, sync can be called to 
ensure that all disk writes are completed before the processor is halted abnormally. 

SEE ALSO 

halt(8), reboot(8), cron(8), fsck(8) 


334 


Last change: 1 November 1983 


Sun Release 3.0 



SYSLOG ( 1 ) 


USER COMMANDS 


SYSLOG ( 1 ) 


NAME 

syslog - make system log entry 
SYNOPSIS 

syslog [ — p ] [ — i name ] [ —level ] [ — ] [ message . . . ] 

DESCRIPTION 

Syslog sends the specified message (or stdin if - is specified) as a system log entry to the syslog daemon 
The log entry is sent to the daemon on the machine specified by the loghost entry in the / etc/ hosts file. 
OPTIONS 

-p Syslog will log its process id in addition to the other information. 

-i name The specified name will be used as the “ident” for the log entry. 

-level The message will be logged at the specified level. The level can be specified numerically, in the 
range 1 through 9, or symbolically using the names specified in the include file 
/usr/include/syslog.h (with the leading LOG_ stripped off). 1 ‘ syslog -HELP” will list the valid 

symbolic level names. Only the superuser can make log entries at levels less than or equal to 
SALERT. 

Each line of the standard input is sent as a log entry. 

FILES 

/usr/ete/in.syslog syslog daemon 
/usr/include/syslog.h for names of logging levels 
SEE ALSO 

syslog(3), syslog(8) 
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NAME 

tail - display the last part of a file 
SYNOPSIS 

tail [ ±nwnber [ Ibc ] [ fr ] ] [ file ] 

DESCRIPTION 

Tail copies the named file to the standard output beginning at a designated place. If no file is named, the 
standard input is used. 

OPTIONS 

Options are all jammed together, not specified separately with their own - signs. 

+number 

Begin copying at distance +number from the beginning of the file. Number is counted in units of 
lines, blocks or characters, according to the appended option 1 , b, or c. When no units are 
specified, counting is by lines. 

—number 

Begin copying at distance -number from the end of the file. Number is counted in units of lines, 
blocks or characters, according to the appended option 1, b, or c. When no units are specified, 
counting is by lines. 

r Copy lines from the end of the file in reverse order. The default for r is to print the entire file this 
way. 

f Follow the file as it grows, that is, don’t quit at end of file, but rather wait and try to read repeat- 
edly in hopes that the file will grow. 

SEE ALSO 

head(l), cat(l), more(l) 

BUGS 

Tails relative to the end of the file are treasured up in a buffer, and thus are limited in length. 

Various kinds of anomalous behavior may happen with character special files. 
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NAME 

talk - talk to another user 
SYNOPSIS 

talk person [ ttyname ] 

DESCRIPTION 

talk is a visual communication program which copies lines from your terminal to that of another user. 

If you wish to talk to someone on your own machine, then person is just the person’s login name. If you 
wish to talk to a user on another host, then person is of the form : 
hostluser or 
ho st. user or 
ho st '.user or 
user @ ho st 

though user@host is perhaps preferred. 

If you want to talk to a user who is logged in more than once, the ttyname argument may be used to indi- 
cate the appropriate terminal name. 

When first called, talk sends the message: 

Message from TalkDaemon@his_machine... 
talk: connection requested by your_name@your_machine. 
talk: respond with: talk your_name@your_machine 
to the user you wish to talk to. At this point, the recipient of the message should reply by typing: 
tutorials talk your_name@your_machine 

It doesn’t matter from which machine the recipient replies, as long as their login-name is the same. Once 
communication is established, the two parties may type simultaneously, with their output appearing in 
separate windows. Typing control-L redraws the screen, while your erase, kill, and word kill characters 
will work in talk as normal. To exit, just type your interrupt character; talk then moves the cursor to the 
bottom of the screen and restores the terminal. 

Permission to talk may be denied or granted by use of the mesg command. At the outset talking is allowed. 
Certain commands, in particular nroff and pr disallow messages in order to prevent messy output. 

FILES 

/etc/hosts to find the recipient’s machine 

/etc/utmp to find the recipient’s tty 

SEE ALSO 

mesg(l), who(l), mail(l), write(l), talkd(8) 
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NAME 

tar - tape archiver 

SYNOPSIS 

tar -ctxru[ovwfbXlmhFpB014578i] [ tarfile ] [ blocksize ] [ exclude file ] 
filenamel filename2 . . . — C dir filenameN . . . 

DESCRIPTION 

tar saves and restores multiple files on a single tarfile (usually a magnetic tape, but it can be any file), tar’s 
actions are controlled by its first argument, the key, a string of characters containing exactly one function 
letter from the set rxtuc and one or more optional function modifiers. Other arguments to tar are file or 
directory names specifying which files to dump or restore. In all cases, appearance of a directory name 
refers to the files and (recursively) subdirectories of that directory. 

FUNCTION LETTERS 

c Create a new tarfile and write the named files onto it 

r Write the named files on the end of the tarfile. Note that this option does not work with quarter-inch 
archive tapes. 

x Extract the named files from the tarfile. If a named file matches a directory whose contents had been 
written onto the tape, this directory is (recursively) extracted. The owner, modification time, and mode 
are restored (if possible). If no file arguments are given, the entire content of the tape is extracted. 
Note that if multiple entries specifying the same file are on the tape, the last one overwrites all earlier 
versions. 

t List all of the names on the tarfile. 

u Add the named files to the tarfile if they are not there or have been modified since last put on the tarfile. 
Note that this option does not work with quarter-inch archive tapes. 

FUNCTION MODIFIERS 
014578 

Select an alternate drive on which the tape is mounted. The numbers 2, 3, 6, and 9 do not specify valid 
drives. The default is ldev/rmt8. 

f Use the next argument as the name of the tarfile instead of Idev/rmt8. If the name is tar writes to 
standard output or reads from standard input, whichever is appropriate. Thus, tar can be used as the 
head or tail of a filter chain, tar can also be used to copy hierarchies with the command: 
tutorial% cd fromdir; tar cf — . | (cd todir; tar xfBp -) 

o Suppress information specifying owner and modes of directories which tar normally places in the 
archive. Such information makes former versions of tar generate an error message like: 

‘<name>/: cannot create’ 
when they encounter it. 

v Normally tar does its work silently; the v (verbose) option displays the name of each file tar treats, pre- 
ceded by the function letter. When used with the t function, v displays the tarfile entries in a form simi- 
lar to Is -1. 

w Wait for user confirmation before taking the specified action. If you use w, tar displays the action to be 
taken followed by the file name, and then waits for a ‘y’ response to proceed. No action is taken on the 
named file if you type anything other than a line beginning with ‘y\ 

b Use the next argument as the blocking factor for tape records. The default blocking factor is 20 blocks. 
The block size is determined automatically when reading tapes (key letters x and t). This determination 
of the blocking factor may be fooled when reading from a pipe or a socket (see the B key letter below). 
The maximum blocking factor is determined only by the amount of memory available to tar when it is 
ran. Larger blocking factors result in better throughput, longer blocks on nine-track tapes, and better 
media utilization. 

X Use the next argument as a file containing a list of named files (or directories) to be excluded from the 
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tarfile when using the key letters c, x, or t. Multiple X arguments may be used, with one exclude file 
per argument. 

1 Display error messages if all links to dumped files cannot be resolved. If 1 is not used, no error mes- 
sages are printed. 

F With one F argument specified, exclude tarfile all directories named SCCS from tarfile. With two argu- 
ments FF, exclude all directories named SCCS, all files with .0 as as their suffix, and all files named 
errs, core, and a.out. 

m Do not restore modification times of extracted files. The modification time will be the time of extrac- 
tion. 

h Follow symbolic links as if they were normal files or directories. Normally, tar does not follow sym- 
bolic links. 

p Restore the named files to their original modes, ignoring the present umask(2). Setuid and sticky infor- 
mation are also restored if you are the super-user. This option is only useful with the x key letter. 

B Force tar to perform multiple reads (if necessary) so as to read exactly enough bytes to fill a block. 
This option exists so that tar can work across the Ethernet, since pipes and sockets return partial blocks 
even when more data is coming. 

i Ignore directory checksum errors. 

If a file name is preceded by -C in a c (create) or r (replace) operation, tar will perform a chdir( 2) to that 
file name. This allows multiple directories not related by a close common parent to be archived using short 
relative path names. For example, to archive files from lusr /include and from /etc, one might use: 
tutorial% tar c -C /usr include -C /etc . 

If you get a table of contents from the resulting tarfile, you will see something like: 
include/ 
include/a.out.h 

and all the other files in lusr/ include 
J 

./chown 

and all the other files in I etc 

Note that the -C pption only applies to one following directory name and one following file name. 
EXAMPLES 

Here is a simple example using tar to create an archive of your home directory onto Idev/rmtO: 
tutorial% cd position yourself in your home directory 

tutorial% tar cvf /dev/rmtO . create the archive 

lots of messages from tar 

tutorial% 

The c option means create the archive; the v option makes tar tell you what it’s doing as it works; the f 
option means that you are specifically naming the file onto which the archive should be placed ( Idev/rmtO 
in this example). 

Now you can read the table of contents from the archive like this: 

tutorials tar tvf /dev/rmtO display table of contents of the archive 

lots of messages from tar 

tutorial% 

You can extract files from the archive like this: 

tutorial^ tar xvf /dev/rmtO extract files from the archive 

lots of messages from tar 

tutorial% 
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If there are multiple archive files on a tape, each is separated from the following one by an end-of-file 
marker, tar does not read the end-of-file mark on the tape after it finishes reading an archive file because 
tar looks for a special header to decide when it has reached the end of the archive. Now if you try to use 
tar to read the next archive file from the tape, tar doesn’t know enough to skip over the end-of-file mark 
and tries to read the end-of-file mark as an archive instead. The result of this is an error message from tar 
to the effect: 

tar: blocksize=0 

This means that to read another archive from the tape, you must skip over the end-of-file marker before 
starting another tar command. You can achieve this via the mt command, as shown in the example below. 
Assume that you are reading from /dev/nrmtO. 

tutorial% tar xvfp /dev/nrmtO read first archive from tape 

lots of messages from tar 

tutorial% mt fsf 1 skip over the end-of-file marker 
tutorial% tar xvfp /dev/nrmtO read second archive from tape 
lots of messages from tar 

tutorial% 

Finally, here is an example using tar to transfer files across the Ethernet, 
from the local machine (tutorial) to a tape on a remote system (krypton): 

tutorial% tar cvfb - 20 files | rsh krypton dd of=/dev/rmtO 
lots of messages from tar 

tutorial % 

In the example above, we are creating a tarfile with the c key letter, asking for verbose output from tar with 
the v option, specifying the name of the output tarfile via the f option (the standard output is where the 
tarfile appears, as indicated by the - sign), and specifying the blocksize (20) with the b option. If you want 
to change the blocksize, you must change the blocksize arguments both on the tar command and on the dd 
command. 

Now, here is how to use tar to get files from a tape on the remote system (krypton) back to the local system 
(tutorial): 

tutorials rsh krypton dd if=/dev/rmtO bs=20b | tar xvBfb - 20 files 
lots of messages from tar 

tutorial% 

In the example above, we are extracting from the tarfile with the x key letter, asking for verbose output 
from tar with the v option, telling tar it is reading from a pipe with the B option, specifying the name of the 
input tarfile via the f option (the standard input is where the tarfile appears, as indicated by the - sign), and 
specifying the blocksize (20) with the b option. 

FILES 

/dev/rmt? half-inch magnetic tape interface 
/dev/rar? quarter-inch magnetic tape interface 
/dev/rst? SCSI tape interface 
/tmp/tar* 

SEE ALSO 

tar(5), cpio(l), dump(8), restore(8) 

BUGS 

Neither the r option nor the u option can be used with quarter-inch archive tapes, since these tape drives 
cannot backspace. 

There is no way to ask for the n ’th occurrence of a file. 

Tape errors are handled ungracefully. 


First, here is how to dump files 
obs=20b 
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The u option can be slow. 

There is no way to selectively follow symbolic links. 

Files with names longer that 100 characters cannot be processed. 
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NAME 

tbl - format tables for nroff or troff 
SYNOPSIS 

tbl [ -ms ] [ -mm ] [ files ] . . . 

DESCRIPTION 

Tbl is a preprocessor for formatting tables for nroff or troff( 1). The input files are copied to the standard 
output, except that lines between .TS and .TE command lines are assumed to describe tables and are refor- 
matted. Details are given in the tbl(l) reference manual. 

If no arguments are given, tbl reads the standard input, so tbl may be used as a filter. When tbl is used with 
eqn or neqn the tbl command should be first, to minimize the volume of data passed through pipes. 

OPTIONS 

-ms Copy the -ms macro package to the front of the output file. 

-mm Copy the -mm macro package to the front of the output file. 

EXAMPLE 

As an example, letting \t represent a tab (which should be typed as a genuine tab) the input 

.TS 

css 

CCS 

ccc 

Inn. 

Household Population 
Town\tHouseholds 
\tNumber\tSize 
Bedminster\t789\t3.26 
Bernards Twp.\t3087\t3.74 
Bernards ville\t201 8\t3 .30 
Bound Brook\t3425\t3.04 
Branchburg\tl644\t3.49 
Bridgewater\t7897\t3.8 1 
Far Hills\t240\t3.19 
.TE 

yields 


Household Population 


Town 

Households 


Number 

Size 

Bedminster 

789 

3.26 

Bernards Twp. 

3087 

3.74 

Bemardsville 

2018 

3.30 

Bound Brook 

3425 

3.04 

Branchburg 

1644 

3.49 

Bridgewater 

7897 

3.81 

Far Hills 

240 

3.19 


SEE ALSO 

Formatting Documents on the Sun Workstation 
troff(l), eqn(l) 


342 


Last change: 14 December 1983 


Sun Release 3.0 



TCOV(l) 


USER COMMANDS 


TCOV(l) 


NAME 

tcov - construct test coverage analysis and statement-by-statement profile 
SYNOPSIS 

tcov [ -a ] [ -n ] file ... 

DESCRIPTION 

Tcov produces a test coverage analysis and statement-by-statement profile of a C or fortran program. 
The coverage data for routines contained in a file named file.c or file./ is taken from the corresponding 
file.d produced by running the C compiler cc(l) or fortran compiler /77(1) with the -a option. 

tcov places an annotated listing of the program with coverage data in file. tcov. Each straight-line segment 
of code (or each line if the -a option to tcov is specified) is prefixed with the number of times it has been 
executed; lines which have not been executed are prefixed with #####. 

Note that the profile produced includes only the number of times each statement was executed, not execu- 
tion times; to obtain times for routines use gprof(l) or prof(l). 

Test coverage data firom several runs will accumulate in the .d files. 

OPTIONS 

-a display an execution count for each statement; if -a is not specified, an execution count is 
displayed only for the first statement of each straight-line segment of code. 

—n display table of the line numbers of the n most frequently executed statements and their execution 
counts. 

SEE ALSO 

cc(l), prof(l), gprof(l) 

FILES 

file.c 
file.f 
file.d 
file.tcov 
/usr/bin/count 
/usr/lib/bb_link.o 

BUGS 

The analyzed program must call exit (2) or return normally for the coverage information to be saved in the 
.d file. 

‘A premature end of file’ message is issued for routines containing no statements. 


input C program file 

input fortran program file 

input test coverage data file 

output test coverage analysis listing file 

preprocessor for test coverage analysis for C program 

entry and exit routines for test coverage analysis 
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NAME 

tee - copy standard output to many files 
SYNOPSIS 

tee [ -i ] [ -a ] [ file ] . . . 

DESCRIPTION 

Tee transcribes the standard input to the standard output and makes copies in the files. 
OPTIONS 

-i Ignore interrupts. 

-a Append the output to the files rather than overwriting them. 


344 


Last change: 2 June 1983 


Sun Release 3.0 



TEKTOOL ( 1 ) 


USER COMMANDS 


TEKTOOL ( 1 ) 


NAME 

tektool - Tektronix 4014 terminal emulator tool 
SYNOPSIS 

tektool [-f fontdir ] [ -s[lcdeg[ce] ] [ -c command line ] [ -r command line ] 

DESCRIPTION 

tektool emulates a Tektronix 4014 terminal with the enhanced graphic module. It does this in much the 
same way as shelltool (see suntools(l)) emulates a regular glass tty. When tektool is invoked, a command 
(usually a shell) is started up, its output and input are connected to the emulator, and a new window is 
formed. The default window is the entire screen. When the emulator is running, buttons TF(1) through 
TF(4), (usually function keys 1-4 (see kbd( 5)) have special meaning. 

TF(1) Unshifted, this is the 4014 PAGE button. Shifted, this is the 4014 RESET button. 

TF(2) Set local mode. 

TF(3) Set on-line mode. 

TF(4) Copy screen. The raster image (lusr/include/rasterfile .h) of the 4014 screen is piped to a com- 
mand found in the TEKCOPY environment variable. The copy button is unaffected by window 
manipulations, and will transmit the contents of the 4014 screen only. 

When in graphics input (GIN) mode and the 4014 crosshairs are visible, the left hand mouse button may be 
used as the space bar to terminate GIN mode. 

OPTIONS 

-f fontdir 

Look for fonts in the directory specified by fontdir. The fonts must be called tekfontO through tekfontZ. 
Fonts must be in vfont(5) format. If this option is not given, the font directory is obtained from the 
TEKFONTS environment variable (if it exists). If no font directory is specified, lusr/lib/fonts is used. 

-s Specifies the Tektronix 4014 strap options with the following modifiers: 

1 Received linefeeds also generate carriage returns, 
c Received carriage returns also generate linefeeds, 
d Received DEL characters are used as low order Y axis addresses, 
e Echo keyboard input. 

g Graphic input mode (GIN) terminator specification. If this strap is followed by a c, GIN mode data 
is terminated by a carriage return. If it is followed by a e, GIN mode data is terminated by a car- 
riage return followed by an EOT character. If this strap is not present, no characters are sent after 
GIN mode data. 

If the -s option is not given, the environment is searched for the TEKSTRAPS variable which provides 
the modifiers. If no straps are specified the d strap is assumed. 

-c command line 

Take terminal emulator input from a shell which in turn runs the command line following the -c option, 
-r command line 

Run command line to provide input to the terminal emulator. This must be the last option, since the 
remainder of the arguments are used. 

CAVEATS 

Like all 4014 emulators, this probably doesn’t duplicate every nuance of the 4014. For instance, certain 
programs redraw stuff already on the screen in order to highlight things with the storage flash. Needless to 
say, this won’t work here (however if you redraw it in writethru mode it will work!!). Also, even though 
the emulator supports the full 4096 address of the 4014, it cannot display this on the screen. All points will 
be rounded to the nearest available pixel. This may cause some funny effects. 

The tektool window may be treated just like other windows; it can be overlaid, moved, reshaped etc. How- 
ever, when the window is reshaped, the contents will not scale. 
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FILES 

/usr/lib/fonts/tekfont[0-3] 

SEE ALSO 

suntools(l) 

Tektronix 4014 and 4014-1 Computer Display Terminal User’s Manual (070-1647-00) 

BUGS 

Special point plot mode is not supported. 

Z axis stuff, except for defocusing, is not supported. 

Defocused alpha characters are not supported. 

The fonts need help. 

Needs scroll bars from the window system to make the whole 4014 screen accessible from a small window. 
There are no user prompts for waiting (for copy) and to remind people about the function keys. 

The current implementation seems to have an effective baud rate of between 4800 and 9600. 
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NAME 

telnet - user interface to the TELNET protocol 
SYNOPSIS 

telnet [ host [ port \ ] 

DESCRIPTION 

telnet communicates with another host using the TELNET protocol. If telnet is invoked without arguments, 
it enters command mode, indicated by its prompt (“telnet>”). In this mode, it accepts and executes the 
commands listed below. If it is invoked with arguments, it performs an open command (see below) with 
those arguments. 

Once a connection has been opened, telnet enters input mode. In this mode, text typed is sent to the remote 
host. To issue telnet commands when in input mode, precede them with the telnet “escape character” (ini- 
tially “*]”, control-right-bracket). When in command mode, the normal terminal editing conventions are 
available. 

TELNET COMMANDS 

The following commands are available. Only enough of each command to uniquely identify it need be 
typed. 

open host [ port ] 

Open a connection to the named host. If the no port number is specified, telnet will attempt to 
contact a TELNET server at the default port. The host specification may be either a host name (see 
hosts (5)) or an Internet address specified in the “dot notation”. 

Close a TELNET session and return to command mode. 

Close any open TELNET session and exit telnet. 

Suspend telnet. This command only works when the user is using the csh. 
escape-char ] 

Set the telnet “escape character”. Control characters may be specified as followed by a sin- 
gle letter; e.g. “control-X” is ““X”. 

Show the current status of telnet. This includes the peer one is connected to, as well as the state 
of debugging. 

Toggle viewing of TELNET options processing. When options viewing is enabled, all TELNET 
option negotiations will be displayed. Options sent by telnet are displayed as “SENT”, while 
options received from the TELNET server are displayed as “RCVD”. 

Toggle carriage return mode. When this mode is enabled any carriage return characters received 
from the remote host will be mapped into a carriage return and a line feed. This mode does not 
affect those characters typed by the user, only those received. This mode is not very useful, but is 
required for some hosts that like to ask the user to do local echoing. 

? [ command ] 

Get help. With no arguments, telnet prints a help summary. If a command is specified, telnet will 
print the help information available about the command only. 

SEE ALSO 

rlogin(lC) 

BUGS 

There is no provision in the standard TELNET protocol to support A S/*Q type commands. This implementa- 
tion is very simple because rlogin( 1C) is the standard mechanism used to communicate locally with hosts. 


close 

quit 

z 

escape [ 

status 

options 

crmod 
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NAME 

test - condition command 

SYNOPSIS 

test expr 

DESCRIPTION 

test evaluates the expression expr, and if its value is true then returns zero exit status; otherwise, a non zero 
exit status is returned, test returns a non zero exit if there are no arguments. 

The following primitives are used to construct expr. 

-b file true if the file exists and is a block special device. 

-c file true if the file exists and is a character special device. 

-d file true if the file exists exists and is a directory. 

-f file true if the file exists and is not a directory. 

-g file true if the file exists and is setgid. 

-h file true if the file exists and is a symbolic link. 

-k file true if the file exists and is sticky. 

-1 string the length of the string. 

-n si true if the length of the string si is nonzero. 

-r file true if the file exists and is readable. 

-sfile true if the file exists and has a size greater than zero. 

-t [fildes ] 

true if the open file whose file descriptor number is fildes (1 by default) is associated with a ter- 
minal device. 

-w file true if the file exists and is writable. 

-x file true if the file exists and is executable. 

-z si true if the length of string si is zero. 

si = s2 true if the strings si and s2 are equal. 

si != s2 true if the strings si and s2 are not equal. 

si true if si is not the null string. 

nl -eq ri2 true if the integers nl and n2 are algebraically equal. Any of the comparisons -ne, -gt, -ge, 
-It, or -le may be used in place of -eq. 

These primaries may be combined with the following operators: 

! unary negation operator 

-a binary and operator 

-o binary or operator 

( expr ) parentheses for grouping. 

-a has higher precedence than -o. Notice that all the operators and flags are separate arguments to test. 
Notice also that parentheses are meaningful to the Shell and must be escaped. 

SEE ALSO 

sh(l), find(l) 
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NAME 

tftp - trivial file transfer program 

SYNOPSIS 

tftp [ host ] 

DESCRIPTION 

Tftp is the user interface to the Internet TFTP (Trivial File Transfer Protocol), which allows users to 
transfer files to and from a remote machine. The remote host may be specified on the command line, in 
which case tftp immediately establishes a connection to the TFTP server on that host. Otherwise, ftp 
awaits connect instructions from the user. 

An account or password on the remote machine is not required. Due to lack of authentication information, 
ftp is only able to access publicly readable files. Search permissions of directories leading to accessed files 
are not checked. 


COMMANDS 

Once ftp is running, it issues the prompt tftp> and recognizes the following commands: 
connect host-name [ port ] 

Set the host (and optionally port) for transfers. Note that the TFTP protocol, unlike the FTP pro- 
tocol, does not maintain connections betweeen transfers; thus, the connect command does not 
actually create a connection, but merely remembers what host is to be used for transfers. You do 
not have to use the connect command; the remote host can be specified as part of the get or put 
commands. 

mode transfer-mode 

Set the mode for transfers; transfer-mode may be one of ascii, binary, or mail. The default is 
ascii. 

put fie ... destination 

Put a file or set of files to the specified destination. Destination can be in one of two forms: a 
filename on the remote host, if the host has already been specified, or a string of the form 
hostflename to specify both a host and filename at the same time. If the latter form is used, the 
hostname specified becomes the default for future transfers. 

get source ...file 

Get a file or set of files from the specified sources. Source can be in one of two forms: a filename 
on the remote host, if the host has already been specified, or a string of the form host filename to 
specify both a host and filename at the same time. If the latter form is used, the last hostname 
specified becomes the default for future transfers. 

quit Exit ftp. 

verbose Toggle verbose mode. Has no effect, 
trace Toggle packet tracing, 
status Show current status. 


rexmt retransmission-timeout 

Set the per-packet retransmission timeout, in seconds. 

timeout total-transmission-timeout 

Set the total transmission timeout, in seconds. 

? [ command-name ... ] 

Print help information. 

BUGS 

The verbose command has no effect. 
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NAME 

time - time a command 

SYNOPSIS 

time [ command ] 

DESCRIPTION 

There are two distinct versions of time-, it is built in to the C-shell, and is an executable program available 
in Ibinltime when using the Bourne shell. In both cases, times are displayed on the diagnostic output 
stream. 

In the case of the C-shell, a time command with no command argument simply displays a summary of time 
used by this shell and its children. When arguments are given the specified simple command is timed and 
the C-shell displays a time summary as described in csh(l). 

The time command in ‘/bin/time’ times the given command, which must be specified, that is, command is 
not optional as it is in the C-shell ’s timing facility. When the command is complete, time displays the 
elapsed time during the command, the time spent in the system, and the time spent in execution of the com- 
mand. Times are reported in seconds. 

EXAMPLES 

The two examples here show the differences between the csh version of time and the version in Ibinltime. 
The example assumes that csh is the shell in use. 
angel% time wc /usr/man/manl/csh.l 
1876 11223 65895 /usr/man/manl/csh.l 
2.7u 0.9s 0:03 91% 3+5k 19+2io lpf+Ow 
angel% /bin/time wc /usr/man/manl/csh.l 
1876 11223 65895 /usr/man/manl/csh.l 
4.3 real 2.7 user 1.0 sys 
angel% 

SEE ALSO 

csh(l) 

BUGS 

Elapsed time is accurate to the second, while the CPU times are measured to the 50th second. Thus the 
sum of the CPU times can be up to a second larger than the elapsed time. 
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NAME 

tip, cu - connect to a remote system 
SYNOPSIS 

tip [ -v ] [ -speed ] system-name 

tip [ -v [ -speed_entry ] [ phone-number ] 

cu phone-number [ -t ] [ -s speed ] [ -a acu ] [ -1 line ] [ -# J 

DESCRIPTION 

tip and cu establish a full-duplex connection to another machine, giving the appearance of being logged in 
directly on the remote computer. It goes without saying that you must have a account on the machine (or 
equivalent) to which you wish to connect. The preferred interface is tip. The cu interface is included for 
those people attached to the ‘call UNIX’ command of the version 7 UNIX system. This manual page 
describes only tip. 

When tip starts up it reads commands from the file .tiprc in your home directory. If you use the — v option 
on the tip command line, tip displays these commands as it executes them. See the discussion on variables 
later on. 

Typed characters are normally transmitted directly to the remote machine (which does the echoing as well). 

A tilde (*"’) appearing as the first character of a line is an escape signal which directs tip to perform some 
special action, tip recognizes the following escape sequences: 

“D ", 

Drop the connection and exit (you may still be logged in on the remote machine). 

"c [name] 

Change directory to name (no argument implies change to your home directory). 

'! Escape to a shell (exiting the shell returns you to tip). 

~> Copy file from local to remote. 

'< Copy file from remote to local. 

"p from [ to ] 

Send a file to a remote UNIX host. When you use the put command, the remote UNIX system runs 
the command string 
cat > to 

while tip sends it the from file. If the to file isn’t specified, the from file name is used. This com- 
mand is actually a UNIX specific version of the ">’ command. 

"t from [ to ] 

Take a file from a remote UNIX host. As in the put command the to file defaults to the from file name 
if it isn’t specified. The remote host executes the command string 
cat > from] echo “A 
to send the file to tip. 

"| Pipe the output from a remote command to a local UNIX process. The command string sent to the 
local UNIX system is processed by the shell. 

'C Connect a program to the remote machine. The command string sent to the program is processed by 
the shell. The program inherits file descriptors 0 as remote line input, 1 as remote line output, and 2 
as tty standard error. 

"# Send a BREAK to the remote system. For systems which don’t support the necessary ioctl call the 
break is simulated by a sequence of line speed changes and DEL characters. 

"s Set a variable (see the discussion below). 

■”Z Stop tip (only available when run under the C-Shell). 

"? Get a summary of the tilde escapes 
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Copying files requires some cooperation on the part of the remote host. When a "> or '< escape is used to 
send a file, tip prompts for a file name (to be transmitted or received) and a command to be sent to the 
remote system, in case the file is being transferred from the remote system. The default end of transmis- 
sion string for transferring a file from the local system to the remote is specified as the ‘oe’ parameter in the 
remote ( 5) file, but may be changed by the set command. While tip is transferring a file the number of lines 
transferred will be continuously displayed on the screen. A file transfer may be aborted with an interrupt 
An example of the dialogue used to transfer files is given below (input typed by the user is shown in bold 
face). 


arpa% tip monet 
[connected] 

. . .( assume we are talking to another UNIX system). . . 

ucbmonet login: sam 

Password: 

monet% cat > sylvester.c 

"> Filename: Sylvester .c 

32 lines transferred in 1 minute 3 seconds 

monet% 

monet% '< Filename: reply .c 
List command for remote host: cat reply .c 
65 lines transferred in 2 minutes 
monet% 

. . .(or, equivalently). . . 
monet% "p Sylvester .c 
. . .( actually echoes as '[put] sylvester.c). . . 

32 lines transferred in 1 minute 3 seconds 
monet% 

monet% "t reply .c 

. . .( actually echoes as '[take] reply. c). . . 

65 lines transferred in 2 minutes 
monet% 

. . .(to print a file locally). . . 

monet% "|Local command: pr -h Sylvester .c | Ipr 

List command for remote host: cat sylvester.c 

monet% "D 

[EOT] 

. . .(back on the local system). . . 

The remote (5) file contains the definitions for remote systems known by tip ; refer to the remote manual 
page for a full description. Each system has a default baud rate with which to establish a connection. If 
this value is not suitable, the baud rate to be used may be specified on the command line, for example: 
tip -300 mds 

When a phone number is specified, instead of a system name, tip looks for an entry in /etc/remote of the 
form t\\>speed_entry . When it finds such an entry, it sets the connection-speed accordingly. If it doesn’t 
find a corresponding entry, tip interprets speed_entry as if it were a system name, resulting in an error mes- 
sage. If you omit -speed_entry , tip uses the tipO entry to set a speed for the connection. 

When tip establishes a connection it sends out a connection message to the remote system. The default 
value for this string may be found in the remote file. 

At any time that tip prompts for an argument (for example, during setup of a file transfer) the line typed 
may be edited with the standard erase and kill characters. A null line in response to a prompt, or an inter- 
rupt, aborts the dialogue and returns you to the remote machine. 
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When tip attempts to connect to a remote system, it opens the associated device with an exclusive-open 
ioctl( 2) call. Thus only one user at a time may access a device. This is to prevent multiple processes from 
sampling the terminal line. In addition, tip honors the locking protocol used by uucp( 1C). 

AUTO-CALL UNITS 

tip may be used to dial up remote systems using a number of auto-call unit’s (ACU’s). When the remote 
system description contains the ‘du’ attribute, tip uses the call-unit (‘cu’), ACU type (‘at’), and phone 
numbers (‘pn’) supplied. Normally tip displays verbose messages as it dials. See remote { 5) for details of 
the remote host specification. 

Depending on the type of auto-dialer being used to establish a connection the remote host may have gar- 
bage characters sent to it upon connection. The user should never assume that the first characters typed to 
the foreign host are the first ones presented to it. The recommended practice is to immediately type a ‘kill’ 
character upon establishing a connection (most UNIX systems support ‘@’ as the initial kill character). 

tip currently supports the Ventel MD-212+ modem and DC Hayes-compatible modems. 

REMOTE HOST DESCRIPTIONS 

Descriptions of remote hosts are normally located in the system-wide file ietdr emote. However, a user 
may maintain personal description files (and phone numbers) by defining and exporting the REMOTE shell 
variable. The remote file must be readable by tip, but a secondary file describing phone numbers may be 
maintained readable only by the user. This secondary phone number file is / etc! phones, unless the shell 
variable PHONES is defined and exported. As described in remote (5), the phones file is read when the host 
description’s phone number(s) capability is an ‘@’. The phone number file contains lines of the form: 

system-name phone-number 

Each phone number found for a system is tried until either a connection is established, or an end of file is 
reached. Phone numbers are constructed from ‘0123456789-=*’, where the *=’ and ‘*’ are used to indicate 
a second dial tone should be waited for (ACU dependent). 

TIP INTERNAL VARIABLES 

tip maintains a set of variables which are used in normal operation. Some of these variables are read-only 
to normal users (root is allowed to change anything of interest). Variables may be displayed and set 
through the “s’ escape. The syntax for variables is patterned after vi and mail. Supplying ‘all’ as an argu- 
ment to the set command displays all variables that the user can read. Alternatively, the user may request 
display of a particular variable by attaching a *?’ to the end. For example ‘escape?’ displays the current 
escape character. 

Variables are numeric, string, character, or Boolean values. Boolean variables are set merely by specifying 
their name. They may be reset by prepending a *!’ to the name. Other variable types are set by appending 
an “=’ and the value. The entire assignment must not have any blanks in it. A single set command may be 
used to interrogate as well as set a number of variables. 

Variables may be initialized at run time by placing set commands (without the “s’ prefix) in a .tiprc file in 
one’s home directory. The -v option makes tip display the sets as- they are made. Comments preceded by 
a *#’ sign can appear in the .tiprc file. 

Finally, the variable names must either be completely specified or an abbreviation may be given. The fol- 
lowing list details those variables known to tip, their abbreviations (surrounded by brackets), and their 
default values. Those variables initialized from the remote file are marked with a **’. A mode is given for 
each variable — capitalization indicates the read or write capability is given only to the super-user. 


Variable 

Type Mode Default 

Description 

[bejautify 

bool 

rw 

true 

discard unprintables when scripting 

[ba]udrate 

num 

rW 

* 

connection baud rate 

[c]har[delay] 

num 

rw 

0 

character delay for file transfers to remote (cl) 

[dial] timeout 

num 

rW 

60 

timeout (seconds) when establishing connection 
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[disconnect 

sc- 

rw 

tttt 

string to send to disconnect (di) 

[ecjhocheck 

hool 

rw 

false 


[eofrjead 

str 

rw 

* 

char’s signifying EOT from the remote host 

[eofw]rite 

str 

rw 

* 

string sent for EOT 

[eol] 

str 

rw 

* 

end of line indicators 

[es]cape 

char 

rw 


command prefix character 

[eflimeout 

num 

rw 

10 

echo check timeout (et) 

[exceptions 

str 

rw 

"\t\n\f\b" 

char’s not discarded due to beautification 

[fo]rce 

char 

rw 

,«r 

force character (default ASCII 255) 

[frjamesize 

num 

rw 

* 

size of buffering between writes on reception 

[h]alf[d]uple[x] bool 

rw 

false 

host is half duplex — do local echo (hd) 

[ho]st 

str 

r 

* 

name of host connected to 

[l]ine[delay] 

num 

rw 

0 

line delay for transfers to remote (dl) 

[l]ocal[e]cho 

bool 

rw 

false 

synonym for halfduplex 

[parjity 

str 

rw 

"none" 

parity to be generated (pa) 

[phones] 

str 

r 

"/etc/phones" 

file for hidden phone numbers 

[pr]ompt 

char 

rW 

‘\n’ 

end of line indicator set by host 

[ra]ise 

bool 

rw 

false 

upper case mapping switch 

[r]aise[c]har 

char 

rw 


interactive toggle for raise (default ascii 255) 

[raw] ftp 

bool 

rw 

false 

send all characters during file transfer (rw) 
do not filter non-printable characters 
do not do translations like \n to \r. 

[rec]ord 

str 

rw 

"tip.record" 

name of script output file 

[remote] 

str 

r 

"/etc/remote" 

system description file 

[sc]ript 

bool 

rw 

false 

session scripting switch 

[tab]expand 

bool 

rw 

false 

expand tabs during file transfers 

[ta]ndem 

bool 

rw 

true 

use XON/XOFF flow control (ta and nt) 

[verb]ose 

bool 

rw 

true 

make noise during file transfers 

[SHELL] 

str 

rw 

"/bin/sh" 

name of shell for '! escape 

[HOME] 

str 

rw 

tut 

home directory for 'c escape 


ENVIRONMENT VARIABLES 

The following variables are read from the environment: 

REMOTE The location of the remote file. 

PHONES The location of the file containing private phone numbers. 
HOST A default host to connect to. 

HOME One’s log-in directory (for chdirs). 

SHELL The shell to fork on a “!’ escape. 

FILES 

7. tiprc initialization file. 

/usr/spool/uucp/LCK..* lock file to avoid conflicts with 
/usr/adm/aculog uucp 

DIAGNOSTICS 

Diagnostics are, hopefully, self explanatory. 

SEE ALSO 

remote(5), phones(5) 

BUGS 

Note that chardelay and linedelay are currently not implemented. 
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NAME 

toolplaces - show current window tool locations, sizes, and other attributes 
SYNOPSIS 

toolplaces [ -u|o|0 ] [ -help ] 

DESCRIPTION 

toolplaces generates position, size, label, and program attributes for the windows running on a window sys- 
tem screen at the time of execution. ( toolplaces doesn’t work when the window system isn’t running.) 

Many people redirect standard output from toolplaces to the .suntools file, so as to reuse the current win- 
dow system attributes each time they execute suntools, the window system program. 

For each window on the screen at execution time, toolplaces shows: 
the tool name 

the "open" window position 
the size of the window in pixels 
the "closed," or icon, window position 
an indicator of whether the window is open or closed 
the label at the top of the window 
the name of the program running in the window, if a 
program is running there 

any flags or options to a program running in the window 

toolplaces describes each window on one output line, as long as necessary, using the current suntools for- 
mat. 

Current suntools format consists of window tool descriptions, one per line, as in this example (the \ indi- 
cates that the current line continues on the next line): 

clocktool -Wp 120 120 -Ws 122 55 -WP 1086 826 -Wi \ 

-W1 " open clock” -S -r -d wdm 
shelltool -Wp 0 510 -Ws 490 343 -WP 256 836 \ 

-Wl "Task Window: /bin/csh" /usr/local/emacs task.file 
shelltool -Wp 491 795 -Ws 580 87 -WP 0 836 -C 
shelltool -Wp 491 166 -Ws 650 567 -WP 702 836 \ 

-Wl due rlogin due 

shelltool -Wp 0 0 -Ws 650 525 -WP 64 836 \ 

-Wl "Small Window: /bin/csh" 
shelltool -Wp 501 0 -Ws 650 812 -WP 128 836 \ 

-Wl "Big Window: /bin/csh" 

OPTIONS 

-u Shows the updated window tool information in the order that you originally specified it. 

-o Shows window tool information in the old suntools format for window attributes, but 

specifies the appropriate tool names for each tool. 

-O Shows window tool information in the old suntools format for window attributes, speci- 

fying toolname as the name for each tool. 

-help Shows help information preceding tool attributes. 

FILES 

'/.suntools Format file for suntools window system program. 

SEE ALSO 

suntools( 1) 

Windows and Window-Based Tools: Beginner's Guide 
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NAME 

touch - update date last modified of a file 
SYNOPSIS 

touch [ — c ] [ — f ] file ... 

DESCRIPTION 

Touch attempts to set the modified date of each file. If the file exists, this is done by reading a character 
from the file and writing it back. 

Touch is valuable when used in conjunction with make(l), where, for instance, you might want to force a 
complete rebuild of a program composed of many pieces. In such a case, you might type, for example: 

% touch *.c 
% make 

and the make would then see that all the .c files were more up to date than all the corresponding .o files, and 
would start the build from scratch. 

OPTIONS 

-c Do not attempt to create a file if it does not exist 

-f Attempt to force the touch in spite of read and write permissions on a file. 
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NAME 

tr - translate characters 
SYNOPSIS 

tr [ -cds ] [ string 1 [ string2 ] ] 

DESCRIPTION 

Tr copies the standard input to the standard output with substitution or deletion of selected characters. The 
arguments stringl and string2 are considered sets of characters. Input characters found in stringl are 
mapped into the corresponding characters of string2. When stringl is short it is padded to the length of 
stringl by duplicating its last character. 

In either string the notation a-b means a range of characters from a to b in increasing ASCII order. The 
character ‘V followed by 1, 2 or 3 octal digits stands for the character whose ASCII code is given by those 
digits. A ‘V followed by any other character stands for that character. 

OPTIONS 

Any combination of the options -cds may be used: 

-c Complement the set of characters in stringl with respect to the universe of characters whose 
ASCII codes are 01 through 0377 octal; 

-d Delete all input characters in stringl ; 

-s Squeeze all strings of repeated output characters that are in string2 to single characters. 

EXAMPLE 

The following example creates a list of all the words in ‘file 1’ one per line in l file2\ where a word is taken 
to be a maximal string of alphabetics. The second string is quoted to protect V from the Shell. 012 is the 
ASCII code for newline. 

tr-cs A-Za-z A012' <filel >file2 

SEE ALSO 

ed(l), ascii(7), expand(l) 

BUGS 

Won’t handle ASCII NUL in stringl or string2; always deletes NUL from input. 
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NAME 

traffic - graphical display of ethemet traffic 
SYNOPSIS 

traffic [ -h host ] [ -s subwindows ] 

DESCRIPTION 

Traffic graphically displays ethemet traffic. It gets statistics from etherd(8c), running on machine host. 
The tool is divided into subwindows, each giving a different view of network traffic. 

OPTIONS 

-h host Specify a host from which to get statistics. The default value of host is the machine that traffic is 
running on. 

-s subwindows 

Specify the number of subwindows to display initially. The default value of subwindows is 1. 

SUBWINDOWS 

To the right of each subwindow is a panel that selects what the subwindow is viewing. If the triangle 
points to size, than the size distribution of packets is displayed. Proto is for protocol, src is for source of 
packet, and dst is for destination of packet. Since it is not possible to show all possible sources, when src is 
selected, only the 8 highest sources are displayed (and similarly for dst). 

For each of these choices, the distribution is displayed by a histogram. The panel above each subwindow 
controls characteristics of the histograms. At the left of the panel are two shaded squares, corresponding to 
the two shades of bars in the histogram. When the triangle shaped pointer is selecting the light colored 
square, then the slider in the center of the panel controls how often the light colored bars are updated. 
When the triangle points to the dark square, then the dark colored bars are selected. To the right of the 
slider is a choice of abs versus rel. This selects whether the height of the histogram is absolute in packets 
per second, or relative in percent of total packets on the ethemet. Next in the panel are three small hor- 
izontal bars. When selected, a horizontal grid appears on the histogram. Finally the button marked delete 
me will delete the subwindow. 

The right hand panel also has a choice for load. Load is represented as a strip chart, rather than a histo- 
gram. The maximum value of the graph represents a load of 100%, that is 10 megabits per second on the 
ethemet. When load is selected, there is only one slider, and no rel versus abs choice. 

At the very top of the tool is a panel that contains filters, as well as a split button that splits the tool and 
creates a new subwindow, and a quit button that exits the tool. The filters apply to all the subwindows. 
When a filter is selected, the word filter will appear in reverse video. There can be more than one filter 
active at the same time. The meaning of each filter is as follows. Src is a host or net, which can be 
specified either by name or address (similarlry for Dst). Proto is an ip protocol, and can either be a name 
(such as udp, icmp) or a number. Lnth is either a packet length, or a range of lengths separated by a dash. 

SEE ALSO 

etherd(8c) 

BUGS 

If multiple copies of traffic are using the same copy of etherd, and one of them invokes a filter, then all the 
copies of traffic will be filtered. 
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NAME 

troff - typeset or format documents 
SYNOPSIS 

troff [-0 pagelist] [ -nN ] [ -sN ] [ -m name][-raN] [ — i ] [ — q ] [-t] [-f] 

[ -w ] [ -b ] [ -a ] [ -p N ] [filenames ] . . . 

DESCRIPTION 

troff formats text in the named files. The output is by default destined for printing on a Graphic Systems 
C/A/T phototypesetter, but suitable postprocessing software can convert the Cl ATT output to a form which 
can be directed to other high-resolution devices. See also the nroff(l) manual page, which describes a for- 
matter which formats text for typewriter-like devices. The capabilities of both troff and nr off ait described 
in Formatting Documents with Nr off and Troff. 

If no filenames argument is present, the standard input is read. An argument consisting of a single minus 
(-) is taken to be a file name corresponding to the standard input 

OPTIONS 

Options may appear in any order so long as they appear before the filenames. 

-olist Print only pages whose page numbers appear in the comma-separated list of numbers and ranges. 
A range N-M means pages N through M; an initial -N means from the beginning to page N; and a 
final N- means from N to the end. 

-nN Number first generated page N. 

— m name 

Prepend the macro file /usr/lib/tmac/tmac./wme to the input files. 

-raN Set register a (one-character) to N. 

-i Read standard input after the input files are exhausted. 

-q Disable echoing during a .rd request. 

-t Direct output to the standard output instead of the phototypesetter. In general, you will have to 
use this option if you don’t have a typesetter attached to the system. 

-a Send a printable ASCII approximation of the results to the standard output. 

Some options of troff only apply if you have a C/A/T typesetter attached to your system. These options are 
here for historical reasons: 


FILES 


-sN Stop every N pages, troff stops the phototypesetter every N pages, produces a trailer to allow 
changing cassettes, and resumes when the typesetter’s start button is pressed. 

-f Refrain from feeding out paper and stopping phototypesetter at the end of the run. 

-w Wait until phototypesetter is available, if currently busy. 

-b Report whether the phototypesetter is busy or available. No text processing is done. 

— pN Print all characters in point size N while retaining all prescribed spacings and motions, to reduce 

phototypesetter elasped time. 

If the file lusr/adm/tracct is writable, troff keeps phototypesetter accounting records there. The integrity of 
that file may be secured by making troff a ’set user-id’ program. 


/tmp/ta* 

/usr/lib/tmac/tmac. * 

/usr/lib/term/* 

/usr/lib/font/* 

/dev/cat 

/usr/adm/tracct 


temporary file 
standard macro files 
terminal driving tables for nroff 
font width tables for troff 
phototypesetter 

accounting statistics for /dev/cat 
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SEE ALSO 

Formatting Documents on the Sun Workstation 

Using nrof f and tr off on the Sun Workstation 

nroff(l), eqn(l), tbl(l), ms(7), me(7), man(7), col(l), checknr(l) 
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NAME 


true, false - provide truth values 
SYNOPSIS 
true 

false 


DESCRIPTION 

True and false are usually used in a Bourne shell script. They test for the appropriate status "true" or 
"false" before running (or failing to run) a list of commands. 

EXAMPLE 


while true 
do 

command list 
done 

SEE ALSO 

csh(l), sh(l), false(l) 

DIAGNOSTICS 

True has exit status zero. 
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NAME 

tset, reset - establish terminal characteristics for the environment 
SYNOPSIS 

tset [ - ] [ -ec ] [ -I ] [ -kc ] [ -n ] [ -Q ] [ — r ] [ — s ] [-S] 

[ -m [ port-ID [ baudrate ] [ '.type ]...][ type ] 

reset . . . 

DESCRIPTION 

tset sets up your terminal, typically when you first log in. It does terminal dependent processing such as 
setting erase and kill characters, setting or resetting delays, sending any sequences needed to properly ini- 
tialized the terminal, and the like, tset first determines the type of terminal involved, and then does neces- 
sary initializations and mode settings. The type of terminal attached to each UNIX port is specified in the 
I etc! tty type database. Type names for terminals may be found in the termcap( 5) database. If a port is not 
wired permanently to a specific terminal (not hardwired) it is given an appropriate generic identifier such as 
dialup. 

reset clears the terminal settings by turning off cbreak and raw modes, output delays and parity checking, 
turns on newline translation, echo and tab expansion, and restores undefined special characters to then- 
default state. It then sets the modes as usual, based on the terminal type (which will probably override 
some of the above). (See ^fy(l) for more information.) reset also uses the rs= and rf= "reset string and 
file" instead of the initialization string and file from /etc/termcap . This is useful after a program dies and 
leaves the terminal in a funny state. Often in this situation, characters will not echo as you type them. You 
may have to type “<LF>reset<LF>” since <CR> may not work. 

When no arguments are specified, tset reads the terminal type from the TERM environment variable and 
re-initializes the terminal, and performs initialization of mode, environment and other options at login time 
to determine the terminal type and set up terminal modes. 

When used in a startup script (.profile for sh users or .login for csh users) it is desirable to give information 
about the type of terminal you will usually use on ports that are not hardwired. These ports are identified in 
letclttytype as dialup or plugboard, etc. Any of the alternate generic names given in termcap may be used 
for the identifier. Refer to the -m option under options for more information. If no mapping applies and a 
final type option, not preceded by a -m, is given on the command line then that type is used; otherwise the 
identifier found in the letclttytype database is used as the terminal type. This should always be the case for 
hardwired ports. 

It is usually desirable to return the terminal type, as finally determined by tset, and information about the 
terminal’s capabilities, to a shell’s environment. This can be done using the -, -s, or -S options. (Refer to 
OPTIONS for more information.) 

For the Bourne shell: export TERM; TERM='tset - options..' 
or using the C-Shell: 

setenv TERM 'tset - options...' 

With the C-Shell, it is convenient to make an alias in your .cshrc file: 

alias tset "setenv TERM 'tset - \!* w 
to allow the command: 
tset 2621 

to be invoked at any time from your login csh. Note to Bourne Shell users: It is not possible to get this 
aliasing effect with a shell script, because shell scripts cannot set the environment of their parent. If a pro- 
cess could set its parent’s environment, none of this nonsense would be necessary in the first place. 

Once the terminal type is known, tset engages in terminal driver mode setting. This normally involves 
sending an initialization sequence to the terminal, setting the single character erase (and optionally the 
line-kill (full line erase)) characters, and setting special character delays. Tab and newline expansion are 
turned off during transmission of the terminal initialization sequence. 
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On terminals that can backspace but not overstrike (such as a CRT), and when the erase character is *#’, the 
erase character is changed as if -e had been used. 

OPTIONS 

- The name of the terminal finally decided upon is output on the standard output This is intended 
to be captured by the shell and placed in the TERM environment variable. 

-ec Set the erase character to be the named character c on all terminals. Default is the backspace key 
on the keyboard, usually A H. The character c can either be typed directly, or entered using the 
circumflex-character notation used here. 

-I Suppress transmitting terminal-initialization strings. 

-kc Set the line kill character to be the named character c on all terminals. Default is “U. The kill 
character is left alone if -k is not specified. The hat notation can also be used for this option. 

-n Specifies that the new tty driver modes should be initialized for this terminal. Probably useless 
since stty new is the default 

-Q Suppress printing the ‘ ‘Erase set to’ ’ and “Kill set to’ ’ messages. 

-r In addition to other actions, reports the terminal type. 

-s Output setenv commands for TERM and TERMCAP. This can be used with 
set noglob 
eval 'tset-s ...' 
unset noglob 

and is preferred to 'setenv TERM 'tset - . . because it makes programs such as vi start up 
much faster. 

-S Similar to the -s option, but outputs two strings suitable for use in csh .login files as follows: 
set noglob 
set t=('tset -S ...') 
setenv TERM $t[l] 
setenv TERMCAP "$t[2]" 
unset t 
unset noglob 

-m [port-ID[baudrate]:type ] ... 

Specify ("map") a terminal type when connected to a generic port (such as dialup or plugboard) 
identified by port-ID . The baudrate argument (see also, stty(l)) can be used to check the baudrate 
of the port and set the terminal type accordingly. The target rate is prefixed by any combination 
of the following operators: 

> is greater than 

@ equals or "at" 

< is less than 

! it is not the case that (negates the above operators) 
to specify the conditions under which the mapping is made. 

In the following example, the terminal type is set to adm3a if the port is a dialup with a speed of 
greater than 300 or to dw2 if the port is a dialup at 300 baud or less. In the third case, the question 
mark preceding the terminal type indicates that the user is to verify the type desired. A null 
response indicates that the named type is correct. Otherwise, the user’s response is taken to be the 
type desired. 

tset-m ’dialup>300:adm3a’ -m ’dialup:dw2’ -m ’plugboard:?adm3a’ 
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To prevent interpretation as metacharacters, the entire argument to -m should be enclosed in sin- 
gle quotes. When using the C-shell, exclamation points should be preceded by a backslash (\). 

EXAMPLES 

These examples all use the - option. A typical use of tset in a .profile or .login will also use the -e and -k 
options, and often the -n or -Q options as well. These options have not been included here to keep the 
examples short. 

Suppose you’re on on a 2621. If you’re running the C-shell, csh, just type: 
set noglob 

set t=(' tset -S 2621') 
setenv TERM $t[l] 
setenv TERMCAP "$t[2]" 
unset t 
unset noglob 

For the Bourne shell, sh: 

set noglob 
eval 'tset -s 2621' 
unset noglob 

You have an hl9 at home which you dial up on, but your office terminal is hardwired and known in 
/etc/ttytype. For the C-shell, csh: 
set noglob 

set t=('tset -S -m dialup:hl9') 
setenv TERM $t[l] 
setenv TERMCAP "$t[2]" 
unset noglob 

For the Bourne shell, sh: 

set noglob 

eval 'tset -s -m dialup:hl9' 
unset noglob 

You have a switch which connects everything to everything, making it nearly impossible to key on what 
port you are coming in on. You use a vtlOO in your office at 9600 baud, and dial up to switch ports at 1200 
baud from home on a 2621. Sometimes you use someone else’s terminal at work, so you want it to ask you 
to make sure what terminal type you have at high speeds, but at 1200 baud you are always on a 2621. Note 
the placement of the question mark, and the quotes to protect the ’>’ and ’?’ from interpretation by the 
shell. For the C-shell, csh: 
set noglob 

set t=(' tset -S -m ’switch>1200:?vtl00’ -m ’switch<= 1200:2621’') 
setenv TERM $t[l] 
setenv TERMCAP ”$t[2]" 
unset noglob 

For the Bourne shell, sh: 

set noglob 

eval 'tset-s-m ’switch>1200:?vtl00’ -m ’switch<=1200:2621’' 
unset noglob 

All of the above entries will fall back on the terminal type specified in /etc/ttytype if none of the conditions 
hold. The following entry is appropriate if you always dial up, always at the same baud rate, on many dif- 
ferent kinds of terminals. Your most common terminal is an adm3a. It always asks you what kind of ter- 
minal you are on, defaulting to adm3a. For the C-shell, csh: 
set noglob 

set t=('tset -S ?adm3a') 
setenv TERM $t[l] 
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setenv TERMCAP "$t[2] M 

unset noglob 

For the Bourne shell, sh: 

set noglob 

eval 'tset -s ?adm3a' 
unset noglob 

If the file letc/tlytype is not properly installed and you want to key entirely on the baud rate, the following 
can be used. For the C-shell, csh: 
set noglob 

set t=('tset -S -m ’>1200:vtl00’ 2621') 
setenv TERM $t[l] 
setenv TERMCAP "$t[2]" 
unset noglob 

For the Bourne shell, sh: 
set noglob 

eval 'tset-s -m ’>1200:vtl00’ 2621' 
unset noglob 

Here is a fancy example to illustrate the power of tset and to hopelessly confuse anyone who has made it 
this far. You dial up at 1200 baud or less on a conceptlOO, sometimes over switch ports and sometimes 
over regular dialups. You use various terminals at speeds higher than 1200 over switch ports, most often 
the terminal in your office, which is a vtlOO. However, sometimes you log in from the university you used 
to go to, over the ARPANET; in this case you are on an ALTO emulating a dm2500. You also often log in 
on various hardwired ports, such as the console, all of which are properly entered in letclttytype. You want 
your erase character set to control H, your kill character set to control U, and don’t want tset to print the 
Erase set to Backspace, Kill set to Control U” message. This example appears to contain an overlong 
line that s been split into two, but when you type in real tset commands, you must enter them entirely on 
one line. For the C-shell, csh: 

set noglob 

set t=('tset -e -k'U -Q -S -m ’switch<=1200:conceptl00’ -m ’switch:?vtl00’ -m 

dialupxonceptl 00 -m arpanet:dm2500') 

setenv TERM $t[l] 

setenv TERMCAP ”$t[2]" 

unset noglob 

For the Bourne shell, sh: 

set noglob 

eval 'tset -e -k'U -Q -s -m ’switch<=1200:conceptl00’ -m ’switch:?vtl00’ -m 
dialupxonceptlOO -m arpanet:dm2500' 
unset noglob 

FILES 

/etc/ttytype port name to terminal type mapping database 

/etc/termcap terminal capability database 

/usr/lib/tabset/* tab setting sequences for various terminals. Pointed to by termcap 
entries. 

SEE ALSO 

csh(l), sh(l), stty(l), ttytype(5), termcap(5), environ(5) 

BUGS 

The tset command is one of the first commands a user must master when getting started on a UNIX system. 
Unfortunately, it is one of the most complex, largely because of the extra effort the user must go through to 
get the environment of the login shell set. Something needs to be done to make all this simpler, either the 
login program should do this stuff, or a default shell alias should be made, or a way to set the environment 
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of the parent should exist. 

It could well be argued that the shell should be responsible for ensuring that the terminal remains in a sane 
state; this would eliminate the need for the reset program. 
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NAME 

tsort- topological sort 
SYNOPSIS 

tsort [ file ] 

DESCRIPTION 

Tsort produces on the standard output a totally ordered list of items consistent with a partial ordering of 
items mentioned in the input file. If no file is specified, the standard input is understood. 

The input consists of pairs of items (nonempty strings) separated by blanks. Pairs of different items indi- 
cate ordering. Pairs of identical items indicate presence, but not ordering. 

SEE ALSO 

lorder(l) 

BUGS 

Uses a quadratic algorithm; not worth fixing for the typical use of ordering a library archive file. 
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NAME 

tty - get terminal name 

SYNOPSIS 

tty [ -s ] 

DESCRIPTION 

Tty prints the pathname of the user’s terminal unless the -s (silent) option is given. In either case, the exit 
value is zero if the standard input is a terminal, and one if it is not. 
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NAME 

ul - do underlining 
SYNOPSIS 

ul [ — i ] [ -t terminal ] [ file ... ] 

DESCRIPTION 

Ul reads the named files (or standard input if none are given) and translates occurrences of underscores to 
the sequence which indicates underlining for the terminal in use, as specified by the environment variable 
TERM, ul uses the letcltermcap file to determine the appropriate sequences for underlining. If the termi- 
nal is incapable of underlining, but is capable of a standout mode then that is used instead. If the terminal 
can overstrike, or handles underlining automatically, ul degenerates to cat( 1). If the terminal cannot under- 
line, underlining is ignored. 

OPTIONS 

-t Override the terminal kind specified in the environment. If the terminal cannot underline, under- 
lining is ignored. 

-i Indicate underlining onto by a separate line containing appropriate dashes this is useful when 
you want to look at the underlining which is present in an nroff output stream on a crt-terminal. 

SEE ALSO 

man(l), nroff(l), colcrt(l) 

BUGS 

Nroff usually generates a series of backspaces and underlines intermixed with the text to indicate underlin- 
ing. Ul makes attempt to optimize the backward motion. 
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NAME 

unget - undo a previous get of an SCCS file 
SYNOPSIS 

/usr/sccs/unget [ -r SID ] [ -s ] [ -n ] file . . . 

DESCRIPTION 

Unget undoes the effect of a get -e done prior to creating the intended new delta. If a directory is named, 
unget behaves as though each file in the directory were specified as a named file, except that non-SCCS 
files and unreadable files are silently ignored. If a name of - is given, the standard input is read with each 
line being taken as the name of an SCCS file to be processed. 

OPTIONS 

Options apply independently to each named file. 

— r SID Uniquely identifies which delta is no longer intended. (This would have been specified by get as 
the “new delta”). The -r option is necessary only if two or more outstanding gets for editing on 
the same SCCS file were done by the same person (login name). A diagnostic results if the 
specified SID is ambiguous, or if it is necessary but omitted from the command line. 

-s Suppress displaying the intended delta’s SID. 

-n Retain the gotten file — it is normally removed from the current directory. 

SEE ALSO 

sccs(l), delta(l), get(l), sact(l). 

Source Code Control System in Programming Tools for the Sun Workstation. 

DIAGNOSTICS 

Use help{\) for explanations. 
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NAME 

uniq - report repeated lines in a file 
SYNOPSIS 

uniq [ -udc [ +n ] [ -n ] ] [ input [ output ] ] 

DESCRIPTION 

Uniq reads the input file comparing adjacent lines. In the normal case, the second and succeeding copies of 
repeated lines are removed; the remainder is written on the output file. Note that repeated lines must be 
adjacent in order to be found; see sort{\). 

OPTIONS 

-u Copy only those lines which are not repeated in the original file. 

-d Write one copy of just the repeated lines. 

The normal output of uniq is the union of the -u and -d options 

-c supersedes -u and -d and generates an output report in default style but with each line preceded 
by a count of the number of times it occurred. 

The n arguments specify skipping an initial portion of each line in the comparison: 

-n The first n fields together with any blanks before each are ignored. A field is defined as a string 
of non-space, non-tab characters separated by tabs and spaces from its neighbors. 

+n The first n characters are ignored. Fields are skipped before characters. 

SEE ALSO 

sort(l), comm(l) 


Sun Release 3.0 


Last change: 30 April 1983 


371 



UNITS ( 1 ) 


USER COMMANDS 


UNITS ( 1 ) 


NAME 

units - conversion program 

SYNOPSIS 

units 


DESCRIPTION 

Units converts quantities expressed in various standard scales to their equivalents in other scales. It works 
interactively in this fashion: 

You have: inch 
You want: cm 

* 2.54000e+00 
/ 3.93701e-01 

A quantity is specified as a multiplicative combination of units optionally preceded by a numeric multiplier. 
Powers are indicated by suffixed positive integers, division by the usual sign: 

You have: 15 pounds force/in2 
You want: atm 

* 1.02069e+00 
/ 9.79730e-01 

Units only does multiplicative scale changes. Thus it can convert Kelvin to Rankine, but not Centigrade to 
Fahrenheit Most familiar units, abbreviations, and metric prefixes are recognized, together with a gen- 
erous leavening of exotica and a few constants of nature including: 

pi ratio of circumference to diameter 

c speed of light 

e charge on an electron 

g acceleration of gravity 

force same as g 

mole Avogadro’s number 

water pressure head per unit height of water 

au astronomical unit 

‘Pound’ is a unit of mass. Compound names are run together, e.g. Tightyear’. British units that differ from 
their US counterparts are prefixed thus: ‘brgallon’. Currency is denoted ‘belgiumfranc’, ‘britainpound’, ... 

For a complete list of units, ‘cat /usr/lib/units’. 

FILES 

/usr/lib/units 


BUGS 

Don’t base your financial plans on the currency conversions. 
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NAME 

uptime - show how long system has been up 

SYNOPSIS 

uptime 

DESCRIPTION 

Uptime prints the current time, the length of time the system has been up, and the average number of jobs 
in the run queue over the last 1, 5 and 15 minutes. It is, essentially, the first line of a w(l) command. 
EXAMPLE 

angel% uptime 

6:47am up 6 days, 16:38, 1 users, load average: 0.69, 0.28, 0.17 
angel% 

FILES 

/vmunix system name list 
SEE ALSO 
w(l) 
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NAME 

users - compact list of users who are on the system 

SYNOPSIS 

users 

DESCRIPTION 

users lists the login names of the users currently on the system in a compact, one-line format: 

tutorial% users 
paul george ringo 
tutorial% 

FILES 

/etc/utmp 

SEE ALSO 

who(l) 
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NAME 

uucp, uulog - unix to unix copy 
SYNOPSIS 

uucp ( -C ] [ -c ] [ -d ] [ -m ] source Jile . . . destination Jile 
uulog [ -ssys ] [ -u user ] 

DESCRIPTION 

uucp copies files named by the source-file arguments to the destination-file argument. A file name may be 
a path name on your machine, or may have the form 

system-name Ipathname 

where ‘system-name’ is taken from a list of system names which uucp knows about. Shell metacharacters 
? * [ ] appearing in the pathname part will be expanded on the appropriate system. 

Pathnames may be one of 

( 1 ) a full pathname; 

(2) a pathname preceded by 1 user /; where user is a username on the specified system and is replaced 
by that user’s login directory; 

(3) a pathname preceded by 7; such a pathname will be replaced by the “public uucp” directory on 
the remote machine; 

(4) anything else is prefixed by the current directory. 

If the result is an erroneous pathname for the remote system the copy will fail. If the destination-file is a 
directory, the last part of the source-file name is used. 

uucp preserves execute permissions across the transmission and gives 0666 read and write permissions (see 
chmod{ 2)). 

uulog maintains a summary log of uucp and uux transactions in the file lusrlspoolluucp/LOGFILE, by gath- 
ering information from partial log files named lusrlspoolluucp/LOG.*.? . It removes the partial log files. 

OPTIONS 

-C Make a copy of outgoing files in the uucp spool directory, rather than copying the source file 
directly to the target system. This lets you remove the source file after issuing the uucp command. 

-c Use the source file when copying out rather than copying the file to the spool directory. This is 
the default. 

-d Make all necessary directories for the file copy. 

-m Send mail to the requester when the copy is complete. 

UULOG OPTIONS 

-ssys Print information about work involving system sys. 

-u user Print information about work done for the specified user. 

FILES 

/usr/spool/uucp spool directory 

/usr/lib/uucp/* other data and program files 

SEE ALSO 

uux(lC), mail(l) 

Uucp Implementation Description in the Sun System Manager’s Manual. 

WARNING 

The domain of remotely accessible files can (and for obvious security reasons, usually should) be severely 
restricted. You will very likely not be able to fetch files by pathname; ask a responsible person on the 
remote system to send them to you. For the same reasons you will probably not be able to send files to 
arbitrary pathnames. 
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BUGS 

All files received by uucp will be owned by uucp. 

The -m option will only work sending files or receiving a single file. Receiving multiple files specified by 
special shell characters ? * [ ] will not activate the -m option. 
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NAME 

uuencode,uudecode - encode/decode a binary file for transmission via mail 
SYNOPSIS 

uuencode [ source-file ] destination-file | mail sysl !sys2!... ! decode 
uudecode [ source-file ] 

DESCRIPTION 

Uuencode and uudecode are used to send a binary file via uucp (or other) mail. This combination of com- 
mands can be used over indirect mail links even when uusend(lC) is not available. 

Uuencode takes the named source-file (or standard input if no source-file is given) and produces an 
encoded version on the standard output, only printing ASCII characters. The mode of the file and the 
destination-file are included so that the file can be recreated with the same mode and name on the remote 
system. 

Uudecode reads an encoded file, strips off any leading and trailing lines added by mailers, and recreates the 
original file with the specified mode and name. 

The intent is that all mail to the user “decode” should be filtered through the uudecode program. This way 
the file is created automatically without human intervention. This is possible on the uucp network by either 
using sendmail or by making rmail be a link to Mail instead of mail. In each case, an alias must be created 
in a master file to get the automatic invocation of uudecode. 

If these facilities are not available, the file can be sent to a user on the remote machine who can uudecode it 
manually. 

The encode file has an ordinary text form and can be edited by any text editor to change the mode or 
remote name. 

SEE ALSO 

uuencode(5), uusend(lC), uucp(lC), uux(lC), mail(l) 

BUGS 

The file is expanded by 35% (3 bytes become 4 plus control information) causing it to tairp longer to 
transmit. 

The user on the remote system who is invoking uudecode (often uucp ) must have write permission on the 
specified file. 
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NAME 

uusend - send a file to a remote host 
SYNOPSIS 

uusend [ — m mode ] sourcefle sysl\sys2\..\remotefile 
DESCRIPTION 

uusend sends a file to a given location on a remote system. The system need not be directly connected to 
the local system, but a chain of uucp links needs to connect the two systems. 

The sourcefile can be meaning to use the standard input. Both of these options are primarily intended 
for internal use of uusend. 

The remotefile can include the 'username or 7 syntax. 

OPTIONS 

— m mode 

Take the mode of the file on the remote end from the octal number specified as mode. The mode 
of the input file is used if the -m option is not specified. 

DIAGNOSTICS 

If anything goes wrong any further away than the first system down the line, you will never hear about it. 
SEE ALSO 

uux(lC), uucp(lC), uuencode(lC) 

BUGS 

This command shouldn’t exist, since uucp should handle it. 

All systems along the line must have the uusend command available and allow remote execution of it 

Some UUCP systems have a bug where binary files cannot be the input to a uux command. If this bug 
exists in any system along the line, the file will show up severely munged. 
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NAME 

uux - unix to unix command execution 
SYNOPSIS 

uux [ - ] [ -gx ] [ -n ] [ -r ] [ -xn ] [ -z ] command-string 
DESCRIPTION 

uux will gather 0 or more files from various systems, execute a command on a specified system and send 
standard output to a file on a specified system. 

The command-string is made up of one or more arguments that look like a shell command line, except that 
the command and file names may be prefixed by system-name!. A null system-name is interpreted as the 
local system. 

File names may be one of 

(1) a full pathname; 

(2) a pathname preceded by ~xxxl ; where xxx is a username on the specified system and is replaced 
by that user’s login directory; 

(3) a pathname preceded by 7; such a pathname is replaced by the “public uucp” directory on the 
remote machine. 

(4) anything else is prefixed by the current directory. 

The option will cause the standard input to the uux command to be the standard input to the command- 
string. 

For example, the command 

uux "Idiff usg!/usr/dan/fl pwba!/a4/dan/fl > Ifi.diff’ 

will get the fl files from the usg and pwba machines, execute a diff command and put the results in fl.diff 
in the local directory. 

Any special shell characters such as <>;| should be quoted either by quoting the entire command-string, or 
quoting the special characters as individual arguments. 

OPTIONS 

-gx set service grade or classification to x . The default is A. 

— n don’t return any indication by mail of success or failure of the job. 

-r don’t start uucico , just queue the job. 

-xn set debugging level to n . (5, 7, and 9 are good numbers to try; they give increasing amounts of 
detail.) 

-z return an indication by mail only if the job fails. 

FILES 

/usr/spool/uucp spool directory 
/usr/lib/uucp/* other data and programs 

SEE ALSO 

uucp(lC), mail(l), sendmail(l) 

D. A. Nowitz, Uucp Implementation Description 

WARNING 

An installation may, and for security reasons generally will, limit the list of commands executable on 
behalf of an incoming request from uux. Typically, a restricted site will permit little other than the receipt 
of mail via uux. 

BUGS 

Only the first command of a shell pipeline may have a system-name!. All other commands are executed on 
the system of the first command. 
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The use of the shell metacharacter * will probably not do what you want it to do. 
The shell tokens « and » are not implemented. 

There is no notification of denial of execution on the remote machine. 
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NAME 

val - validate SCCS file 

SYNOPSIS 

/usr/sccs/val - 

/usr/sccs/val [ -s ] [ -r SID ] [ -m name ] [ -y type ] file . . . 

DESCRIPTION 

Val determines if the specified file is an SCCS file meeting the characteristics specified by the optional 
argument list. Arguments to val may appear in any order. 

Val has a special argument, which causes reading of the standard input until an end-of-file condition is 
detected. Each line read is independently processed as if it were a command line argument list. 

Val generates diagnostic messages on the standard output for each command line and file processed and 
also returns a single 8-bit code upon exit as described below. 

OPTIONS 

Options apply independently to each named file on the command line. 

-s Silence diagnostic messages normally generated for errors detected while processing the specified 
files. 

-r SID The argument value SID (SCCS /Dentification String) is an SCCS delta number. A check is made 
to determine if the SID is ambiguous (for instance, rl is ambiguous because it physically does not 
exist but implies 1.1, 1.2, etc. which may exist) or invalid (for instance, rl.O or r 1.1.0 are invalid 
because neither case can exist as a valid delta number). If the SID is valid and not ambiguous, a 
check is made to determine if it actually exists. 

-m name 

name is compared with the SCCS %M% keyword in file. 

-y type type is compared with the SCCS %Y% keyword in file. 

The 8-bit code returned by val is a disjunction of the possible errors, that is, can be interpreted as a bit 
string where (moving from left to right) set bits are interpreted as follows: 

bit 0 = missing file argument; 

bit 1 = unknown or duplicate option; 

bit 2 = corrupted SCCS file; 

bit 3 = can’t open file or file not SCCS; 

bit 4 = SID is invalid or ambiguous; 

bit 5 = SID does not exist; 

bit 6 = %Y%, -y mismatch; 

bit 7 = %M%, -m mismatch; 

Note that val can process two or more files on a given command line and in turn can process multiple com- 
mand lines (when reading the standard input). In these cases an aggregate code is returned — logical OR 
of the codes generated for each command line and file processed. 

SEE ALSO 

sccs(l), admin(l), delta(l), get(l), prs(l). 

Source Code Control System in Programming Tools for the Sun Workstation. 

DIAGNOSTICS 

Use help{\) for explanations. 

BUGS 

Val can process up to 50 files on a single command line. Any number above 50 will produce a core dump. 
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NAME 

vax - is current machine a vax 
SYNOPSIS 


if vax; then § 

(sh) 

if { vax } then 

(csh) 

endif 



DESCRIPTION 

The vax command is, on VAX’en, the same as frue(l); on Sun Workstations and other machines it is the 
same as false( 1). 

SEE ALSO 

false(l), sun(l), true(l) 
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NAME 

vfontinfo - inspect and print out information about UNIX fonts 
SYNOPSIS 

vfontinfo [ — v ] fontname [ characters ] 

DESCRIPTION 

vfontinfo allows you to examine a font in the UNIX format. It prints out all the information in the font 
header and information about every non-null (width > 0) glyph. This can be used to make sure the font is 
consistent with the format. 

The fontname argument is the name of the font you wish to inspect. It writes to standard output. If it can’t 
find the file in your working directory, it looks in lusr/lib/vfont (the place most of the fonts are kept). 

The characters, if given, specify certain characters to show. If omitted, the entire font is shown. 

If the -v (verbose) flag is used, the bits of the glyph itself are shown as an array of X’s and spaces, in addi- 
tion to the header information. 

SEE ALSO 

vpr(l), vfont(5), vswap(l), vwidth(l) 
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NAME 

vgrind - grind nice listings of programs 
SYNOPSIS 

vgrind [ -f ] [ - ] [ -t ] [ -n ] [ -x ] [ -W ] [ -sn ] [ -h header ] [ -d file ] [ -1 language ] filename . . . 
DESCRIPTION 

Vgrind formats the program sources which are file arguments in a nice style using trojf. Comments are 
placed in italics, keywords in bold face, and the name of the current function is listed down the margin of 
each page as it is encountered. 

Vgrind runs in two basic modes, filter mode or regular mode. In filter mode vgrind acts as a filter in a 
manner similar to tbl. The standard input is passed directly to the standard output except for lines brack- 
eted by the trojf -Xtk& macros: 

.vS - starts processing 

.vE - ends processing 

These lines are formatted as described above. The output from this filter can be passed to trojf for output. 
There need be no particular ordering with eqn or tbl. 

In regular mode vgrind accepts input files, processes them, and passes them to trojf for output. 

In both modes vgrind passes any lines beginning with a decimal point without conversion. 

OPTIONS 

-f force filter mode. 


- take from standard input (default if -f is specified). 

-t similar to the same option in trojf, that is, formatted text goes to the standard output. 

-n do not make keywords boldface. 

-x output the index file in a ‘pretty’ format. The index file itself is produced whenever vgrind is run 

with a file called index in the current directory. The index of function definitions can then be run 
off by giving vgrind the -x option and the file index as argument 

-W force output to the (wide) Versatec printer rather than the (narrow) Varian. 

-s specifies a point size to use on output (exactly the same as the argument of a trojf.ps (point size) 
request. 

-h specifies a particular header to put on every output page (default is the file name). 

-d specifies an alternate language definitions file (default is /usr/lib/vgrindefs). 

-1 specifies the language to use. Currently known are C (-1c the default), CSH (-lcsh), ICON (-11), 

ISP (— i), LDL (-1LDL), MODEL (-1m), PASCAL (-Ip), FORTRAN (-If) RATFOR (-lr), and SHELL 
(— Ish). 


FILES 

index 

/usr/lib/tmac/tmac.vgrind 

/usr/lib/vfontedpr 

/usr/lib/vgrindefs 


file where source for index is created 
macro package 
preprocessor 
language descriptions 


SEE ALSO 

troff(l) 


BUGS 

Vfontedpr assumes that a certain programming style is followed: 

For C - function names can be preceded on a line only by spaces, tabs, or an asterisk. The parenthesized 
arguments must also be on the same line. 
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For PASCAL - function names need to appear on the same line as the keywords function or procedure. 

For FORTRAN - function names need to appear on the same line as the keywords function or subroutine. 

If these conventions are not followed, the indexing and marginal function name comment mechanisms will 
fail. 

More generally, arbitrary formatting styles for programs mostly look bad. The use of spaces to align 
source code fails miserably; if you plan to vgrind your program you should use tabs. This is somewhat 
inevitable since the font used by vgrind is variable width. 

The mechanism of ctags in recognizing functions should be used here. 
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NAME 

vi - screen oriented (visual) display editor based on ex 
SYNOPSIS 

vi [ -R ] [ -r ] [ -t tag ] [ +command ] [ -x ] [ -w nnn ] [ -I ]file . . . 

DESCRIPTION 

Vi (visual) is a display oriented text editor based on ex. ex and vi are in fact the same text editor; it is possi- 
ble to get to the command mode of ex from within vi and vice-versa. 

OPTIONS 

-R edit the file in read-only state. You can achieve the same effect with the view command. 

-r recover the indicated files after a crash. 

-t tag edit the file containing the tag tag . A tags database must have been built previously using the 
ctags( 1) command. 

+command 

start the editing session by executing command. 

-w nnn set the default window (number of lines on your terminal) to nnn — this is useful if you are dial- 
ling into the system over a slow ’phone line. 

-x prompt for a key to be used in encrypting the file being edited. 

-1 set up for editing LISP programs. 

FILES 

Seeex(l). 

SEE ALSO 

Editing Text Files on the Sun 
ex(l) 

BUGS 

Software tabs using A T work only immediately after the autoindent. 

Left and right shifts on intelligent terminals don’t make use of insert and delete character operations in the 
terminal. 

The wrapmargin option can be fooled since it looks at output columns when blanks are typed. If a long 
word passes through the margin and onto the next line without a break, then the line won’t be broken. 

Repeating a change which wraps over the margin when wrapmargin is in effect doesn’t generally work 
well: sometimes it just makes a mess of the change, and sometimes even leaves you in insert mode. A way 
to work around the problem is to replicate the changes using yank and put. 

Insert/delete within a line can be slow if tabs are present on intelligent terminals, since the terminals need 
help in doing this correctly. 

Saving text on deletes in the named buffers is somewhat inefficient. 

The source command does not work when executed as rsource; there is no way to use the :append, 
:change, and :insert commands, since it is not possible to give more than one line of input to a : escape. 
To use these on a :global you must Q to ex command mode, execute them, and then reenter the screen edi- 
tor with vi or open. 

When using the -r option to recover a file, you must write the recovered text before quitting or you will 
lose it. Vi does not prevent you from exiting without writing unless you make changes. 

RESTRICTIONS 

The encryption facilities of vi are not available on software shipped outside the U.S. 
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NAME 

view - view a file without changing it using the vi visual editor 
SYNOPSIS 

view [ — t tag ] [ — r ] [ +command ] [ — 1 ] [ — w n ] name . . . 

DESCRIPTION 

View uses the vi (visual) or display oriented text editor to browse through a file interactively without actu- 
ally making any changes to the file. It is possible to get to the command mode of ex from within view and 
vice-versa, just as when using vi. 

SEE ALSO 

Editing Text Files on the Sun Workstation 
ex(l), vi(l) 
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NAME 

vplot - plot graphics on the Versatec 
SYNOPSIS 

vplot [ -W ] [ -V ] t -b Ipr-arg ] file 
DESCRIPTION 

Vplot reads plot (5) format graphics input from the file specified by file (standard input if no file is specified) 
and produces a plot on the Varian or Versatec. 

OPTIONS 

-W force output to the (wide) Versatec printer rather than the standard Versatec printer. 

-V force output to the standard Versatec printer. 

-b Ipr-arg 

arg (the next argument on the command line) specifies extra arguments to lpr( 1). 

SEE ALSO 

plot(lG), lpr(l), plot(5) 
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NAME 

vpr, vprm, vpq, vprint - raster printer/plotter spooler 
SYNOPSIS 

vpr [ -W ] [ -1 ] [ -v ] [ -t [ -1234 font ] ] [ -w ] [ -wwidth ] [ -m ] [ name ... ] 

vprm [ id ... ] [ filename ... ] [ owner ... ] 

vpq 

vprint [ -W ] file ... 

DESCRIPTION 

Vpr causes the named files to be queued for printing or typeset simulation on one of the available raster 
printer/plotters. If no files are named, the standard input is read. By default the input is assumed to be line 
printer-like text For very wide plotters, the input is run through the filter lusrllib/sidebyside giving it an 
argument of-wl06 which arranges it four pages adjacent with 90 column lines (the rest is for the left mar- 
gin). Since there are 8 lines per inch in the default printer font, vpr thus produces 86 lines per page (the top 
and bottom lines are left blank). 

The following options are available: 

Print the input in a more literal manner. Page breaks are not inserted, and most control 
characters (except format effectors: \n, \f, etc.) are printed (many control characters 
print special graphics not in the ASCII character set.) Tab and underline processing is 
still done. If this option is not given, control characters which are not format effectors 
are ignored, and page breaks are inserted after an appropriate number of lines have been 
printed on a page. 

Queues files for printing on a wide output device, if available. Normally, files are 
queued for printing on a narrow output device. 

Specifies a font to be mounted on font position z. The daemon will construct a .railmag 
file referencing lu.srlliblvfontlname.size. 

Report by mail{\) when printing is complete. 

(Applicable only to wide output devices.) Do not run the input through sidebyside. 
Such processing has been done already, or full (440 character) printer width is desired. 

-wwidth Use width width rather than 90 for sidebyside. 

-v Use the filter lusr/lib/vrast to convert the vectors to raster. The named files must be a 

parameter and vector file (in that order) created by plot{ 3X) routines. 

-t Use the filter lusr/liblvcat to typeset the input on the printer/plotter. The input must have 

been generated by troff{ 1) run with the -t option. This is not normally run directly to 
wide output devices, since it is wasteful to run only one page across. The program 
vtro Jf(l) is normally used and arranges, using vsort for printing to occur four pages 
across, conserving paper. 

Vprm removes entries from the raster device queues. The id, filename or owner should be that reported by 
vpq. All appropriate files will be removed. Both queues are always searched. The id of each file removed 
from the queue will be printed. 

Vpq prints the queues. Each entry in the queue is printed showing the owner of the queue entry, an 
identification number, the size of the entry in characters, and the file which is to be printed. The id is useful 
for removing a specific entry from the printer queue using vprm 

Vprint is a shell script which pr’s a copy of each named file on one of the electrostatic printer/plotters. The 
files are normally printed on a narrow device; -W option causes them to be printed on a wide device. 

FILES 

/usr/spool/v?d/* device spool areas 

/usr/lib/v?d daemons 

/usr/lib/vpd Versatec daemon 


-W 

-1234 

-m 

-w 
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/usr/lib/vpf 

/usr/lib/*vcat 

/usr/lib/vrast 

/usr/lib/sidebyside 


filter for printer simulation 
filter for typeset simulation 
filter for plot 
filter for wide output 


SEE ALSO 

troff(l), vfont(5), vp(4), pti(l), vtroff(l), plot(3X) 


BUGS 

The l’s (one’s) and l’s (lower-case el’s) in a Benson-Varian’s standard character set look very similar; cau- 
tion is advised. 


A versatec’s hardware character set is rather ugly. V print should use one of the constant width fonts to 
produce prettier listings. 
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NAME 

vswap - convert a foreign font file 

SYNOPSIS 

/usr/Iib/vswap [ -r ] 

DESCRIPTION 

Without the -r option, vswap translates its standard input (which must be a vfont file in the reversed-byte 
order) into a locally correct vfont file on its standard output. With the -r option, vswap translates its stan- 
dard input (which must be a vfont file in the local-byte order) into a byte-reversed vfont file on its standard 
output. 

The UNIX vfont representation for fonts is a binary file containing machine-dependent elements short 

(16-bit) integers, in particular. There are (at least) two common ways of representing a 16-bit integer. A 
program compiled on a VAX will expect the VAX format, while the same program compiled on a 
Motorola 68000 will expect 68000 format Vswap can be used to convert font files created on a VAX to 
the format required to use them on the Sun. It can also convert Sun-format font files to VAX format (with 
the — r option). Since the font files are in the byte order of the local machine, programs which access the 
font files don’t need to be concerned with byte-swapping issues. This could be considered a bug. 

SEE ALSO 

troff(l), vfont(5) 

BUGS 

A machine-independent font format should be defined. 
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NAME 

vtroff - troff to a raster plotter 
SYNOPSIS 

vtroff [ -w ] [ -F majorfont ] [ -123 minorfont ] [ -1 length ] [ -x ] troff arguments 
DESCRIPTION 

Vtroff mm troff {Y) sending its output through various programs to produce typeset output on a raster plotter 
such as a Benson-Varian or or a Versatec. The -W option specifies that a wide output device be used; the 
default is to use a narrow device. The -1 (lower case 1) option causes the output to be split onto successive 
pages every length inches rather than the default 11”. 

The default font is a Hershey font. If some other font is desired you can give a -F argument and then the 
font name. This will place normal, italic and bold versions of the font on positions 1, 2, and 3. To place a 
font only on a single position, you can give an argument of the form -n and the minor font name. A .r will 
be added to the minor font name if needed. Thus “vtroff -ms paper” will set a paper in the Hershey font, 
while “vtroff -F nonie -ms paper” will set the paper in the (sans serif) nonie font. The -x option asks for 
exact simulation of photo-typesetter output. (I.e. using the width tables for the C.A.T. photo-typesetter) 

FILES 

/usr/lib/tmac/tmac.vcat 
/usr/lib/fontinfo/* 

/usr/lib/vfont 

SEE ALSO 

troff(l), vfont(5), vpr(l) 

BUGS 

Since some macro packages work correctly only if the fonts named R, I, B, and S are mounted, and since 
the Versatec fonts have different widths for individual characters than the fonts found on the typesetter, the 
following dodge was necessary: If you don’t use the “.fp” troff directive then you get the widths of the 
standard typesetter fonts suitable for shipping the output of troff over the network to the computer center A 
machine for phototypesetting. If, however, you remount the R, I, B and S fonts, then you get the width 
tables for the Versatec. 


default font mounts and bug fixes 
fixes for other fonts 
directory containing fonts 
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NAME 

vwidth - make troff width table for a font 
SYNOPSIS 

/usr/lib/vwidth fontfile pointsize > fta.c 
cc -c ftxx.c 

mv fta.o /usr/lib/font/ftrc 
DESCRIPTION 

Vwidth translates from the width information stored in the vfont style format to the format expected by 
troff. Troff wants an object file in a.out(5) format. (This fact does not seem to be documented anywhere.) 
Troff should look directly in the font file but it doesn’t. 

Vwidth should be used after editing a font with fontedit(l). It is not necessary to use vwidth unless you 
have made a change that would affect the width tables. Such changes include numerically editing the 
width field, adding a new character, and moving or copying a character to a new position. It is not always 
necessary to use vwidth if the physical width of the glyph (e.g. the number of columns in the bit matrix) 
has changed, but if it has changed much the logical width should probably be changed and vwidth run. 

Vwidth produces a C program on its standard output. This program should be run through the C compiler 
and the object (that is, the .o file) saved. The resulting file should be placed in /usr/lib/font in the file ftxx 
where is a one or two letter code that is the logical (internal to troff) font name. This name can be found by 
looking in the file /usr/lib/fontinfo//naffj£* where /name is the external name of the font 

SEE ALSO 

fontedit(l), vfont(5), troff(l), vtroff(l) 
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NAME 

w - who is on and what they are doing 

SYNOPSIS 

w [ -h ] [ -s ] [ user ] 

DESCRIPTION 

W displays a summary of the current activity on the system, including what each user is doing. The head- 
ing line shows the current time of day, how long the system has been up, the number of users logged into 
the system, and the load averages. The load average numbers give the number of jobs in the run queue 
averaged over 1, 5 and 15 minutes. 

The fields displayed are: the users login name, the name of the tty the user is on, the time of day the user 
logged on (in hours minutes), the idle time — that is, the number of minutes since the user last typed any- 
thing (in hours:minutes), the CPU time used by all processes and their children on that terminal (in 
minutes:seconds), the CPU time used by the currently active processes (in minutes:seconds), the name and 
arguments of the current process. 

If a user name is included, output is restricted to that user. 

OPTIONS 

-h Suppress the heading. 

-s Produce a short form of output. In the short form, the tty is abbreviated, the login time and cpu 
times are left off, as are the arguments to commands. 

-1 Produce a long form of output, which is the default. 

EXAMPLE 

angel% w 

7:36am up 6 days, 16:45, 1 users, load average: 0.20, 0.23, 0.18 
User tty login@ idle JCPU PCPU what 

henry console 7:10am 1 10:05 4:31 w 

angel% 

FILES 

/etc/utmp 

/dev/kmem 

/dev/drum 

SEE ALSO 

who(l), ps(l), utmp(5) 

BUGS 

The notion of the ‘current process’ is muddy. The current algorithm is ‘the highest numbered process on 
the terminal that is not ignoring interrupts, or, if there is none, the highest numbered process on the termi- 
nal’. This fails, for example, in critical sections of programs like the shell and editor, or when faulty pro- 
grams running in the background fork and fail to ignore interrupts. In cases where no process can be 
found, w prints 

The CPU time is only an estimate, in particular, if someone leaves a background process running after log- 
ging out, the person currently on that terminal is ‘charged’ with the time. 

Background processes are not shown, even though they account for much of the load on the system. 

Sometimes processes, typically those in the background, are printed with null or garbaged arguments. In 
these cases, the name of the command is printed in parentheses. 

W does not know about the new conventions for detecting background jobs. It will sometimes find a back- 
ground job instead of the right one. 
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NAME 

wait - await completion of process 
SYNOPSIS 
wait 

DESCRIPTION 

Wait until all processes started with & or bg have completed, and report on abnormal terminations. 

Because the wait (2) system call must be executed in the parent process, the Shell itself executes wait, 
without creating a new process. 

SEE ALSO 

sh(l), csh(l) 

BUGS 

Not all the processes of a 3- or more-stage pipeline are children of the Shell, and thus can’t be waited for. 
(This bug does not apply to cj/i(1).) 
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NAME 

wall - write to all users 

SYNOPSIS 

wall [ -a ] [ file ] 

DESCRIPTION 

Wall reads its standard input until an end-of-file. It then sends this message, preceded by ‘Broadcast Mes- 
sage to all logged in users. Normally, ptys that do not correspond to rlogin sessions are ignored. Thus 
when in suntools(l), the message appears only on the console window. However -a will send the message 
even to such ptys. 

The sender should be super-user to override any protections the users may have invoked. 

FILES 

/dev/tty? 

/etc/utmp 

SEE ALSO 

mesg(l), write(l) 
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NAME 

wc - word count 
SYNOPSIS 

wc [ -lwc ][ file ... ] 

DESCRIPTION 

Wc counts lines, words, and characters in the named files, or in the standard input if no file names appear. 
A word is a string of characters delimited by spaces, tabs, or newlines. 

OPTIONS 

If an argument beginning with one of ‘lwc’ is present, the specified counts are selected by the letters: 

1 Count lines, 

w Count words, 

c Count characters. 

The default is —lwc (count lines, words, and characters). 

EXAMPLE 

angel% wc /usr/man/manl/{csh.l,sh.l,telnet.l} 


1876 

11223 

65895 

/usr/man/man 1/csh. 1 

674 

3310 

20338 

/usr/man/manl/sh.l 

260 

1110 

6834 

/usr/man/man 1/telnet. 1 

2810 

15643 

93067 

total 


angel% 
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NAME 

what - identify the version of files 

SYNOPSIS 

what files 

DESCRIPTION 

What searches the given files for all occurrences of the pattern that get(l) substitutes for %Z% (this is 
@(#) at this printing) and prints out what follows until the first ", >, new-line, \, or null character. For 
example, if the C program in file pro gram. c contains 

char ident[] = " @(#)identification information”; 

and program.c is compiled to yield programs and a. out, the command 

what f.c f.o a.out 


will print 


f.c: 

identification information 

f.o: 

identification information 

a.out: 

identification information 


What is intended to be used in conjunction with the SCCS command get( 1), which automatically inserts 
identifying information, but it can also be used where the information is inserted manually. 

SEE ALSO 

sccs(l), get(l), help(l), file(l). 

The Source Code Control System in Programming Tools for the Sun System 

DIAGNOSTICS 

Use help(l) for explanations. 

BUGS 

It’s possible that an unintended occurrence of the pattern @(#) could be found just by chance, but this 
causes no harm in nearly all cases. 
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NAME 

whatis — describe what a command is 
SYNOPSIS 

whatis command . . . 

DESCRIPTION 

Whatis looks up a given command and displays the header line from the manual section. You can then run 
the man( 1) command to get more information. If the line starts ‘name(section) . . . you can do 
man section name to get the documentation for it. Try whatis ed and then you should do man 1 ed to 
get the manual page for ed. 

Whatis is actually just the -f option to the man(l) command. 

FILES 

/usr/man/whatis Data base 

SEE ALSO 

man(l), catman(8) 
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NAME 

whereis - locate source, binary, and/or manual for program 
SYNOPSIS 

whereis [ -sbm ] [ -u ] [ -BMS dir . . . -f ] filename . . . 

DESCRIPTION 

Whereis locates source/binary and manuals sections for specified files. The supplied names are first 
stripped of leading pathname components and any (single) trailing extension of the form .ext, for example, 
,c. Prefixes of s. resulting from use of source code control are also dealt with. Whereis then attempts to 
locate the desired program in a list of standard places. 

OPTIONS 

-b Search only for binaries. 

-s Search only for sources. 

-m Search only for manual sections. 

-u Search for unusual entries. A file is said to be unusual if it does not have one entry of each 

requested type. Thus whereis -m -u * asks for those files in the current directory which have 
no documentation. 

-B Change or otherwise limit the places where whereis searches for binaries. 

-M Change or otherwise limit the places where whereis searches for manual sections. 

-S Change or otherwise limit the places where whereis searches for sources. 

-f Terminates the last directory list and signals the start of file names, and must be used when any of 

the -B, -M, or -S options are used. 

EXAMPLE 

Find all files in lusrlbin which are not documented in lusr/man/manl with source in lusrlsrc/cmd : 
angel% cd /usr/ucb 

angel% whereis -u -M /usr/man/manl -S /usr/src/cmd -f * 

FILES 

/usr/src/* 

/usr/{doc,man}/* 

/lib, /etc, /usr/{lib, bin, ucb,old,new, local} 

BUGS 

Since whereis uses chdir(2) to run faster, pathnames given with the -M, -S, or -B must be full; that is, 
they must begin with a 7’. 


400 


Last change: 1 February 1985 


Sun Release 3.0 



WHICH ( 1 ) 


USER COMMANDS 


WHICH ( 1 ) 


NAME 

which - locate a program file including aliases and paths ( csh only) 

SYNOPSIS 

which [ name ] . . . 

DESCRIPTION 

Which takes a list of names and looks for the files which would be executed had these names been given as 
commands. Each argument is expanded if it is aliased, and searched for along the user’s path. Both aliases 
and path are taken from the user’s .cshrc file. 

FILES 

"/.cshrc source of aliases and path values 

DIAGNOSTICS 

A diagnostic is given for names which are aliased to more than a single word, or if an executable file with 
the argument name was not found in the path. 

BUGS 

Only aliases and paths from "/.cshrc are used; importing from the current environment is not attempted. 
Must be executed by a csh, since only csh’s know about aliases. 

To compensate for 7 . cshrc files in which aliases depend upon the prompt variable being set, which sets 
this variable. If the 7 . cshrc produces output or prompts for input when prompt is set, which may produce 
some strange results. 
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NAME 

who - who is on the system 
SYNOPSIS 

who [ who-file ] [ am i ] 

DESCRIPTION 

Used without arguments, who lists the login name, terminal name, and login time for each current UNIX 
user, who gets this information from the /etc/utmp file. 

If a filename argument is given, the named file is examined instead of /etc/utmp. Typically the named file 
is lusrladmlwtmp, which contains a record of all logins since it was created. In this case, who lists logins, 
logouts, and crashes. Each login is listed with user name, terminal name (with ‘/dev/’ suppressed), and 
date and time. Logouts produce a similar line without a user name. Reboots produce a line with in 
place of the device name, and a fossil time indicating when the system went down. Finally, the adjacent 
pair of entries T and *}’ indicate the system-maintained time just before and after a date command 
changed the system’s idea of the time. 

With two arguments, as in ‘who am i’ (and also ‘who is who’), who tells who you are logged in as: it 
displays your hostname, login name, terminal name, and login time. 

EXAMPLES 

angel% who am i 

angellhenry ttypO Apr 27 11:24 
angel% 

krypton% who 

mktg ttymO Apr 27 11:11 
shannon ttypO Apr 27 11:25 
henry ttypl Apr 27 11:30 
krypton% 

FILES 

/etc/utmp /usr/adm/wtmp 
SEE ALSO 

whoami(l), wtmp(5), w(l) 
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NAME 

whoami - display effective current username 
SYNOPSIS 

whoami 

DESCRIPTION 

whoami displays the username of whoever is currently logged in. whoami works even if you’ve used su to 
pick up another username, while ‘who am i’ does not since it gets its information from the letclutmp file. 

In other words, 

whoami shows who you are now, while 

who am i shows who you where when you logged in. 

FILES 

/etc/passwd username data base 

SEE ALSO 

who(l) 
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NAME 

write - write to another user 
SYNOPSIS 

write user [ ttyname ] 

DESCRIPTION 

Write copies lines from your standard input to user ’s screen. 

When you type a write command, the person you’re writing to sees a message like this: 

Message from hostnamelyoumame on yourttyname at hh:mm . . . 

After typing the write command, enter the text of your message. What you type appears line-by-line on the 
other user’s screen. Conclude by typing an end of file indication ('D) or an interrupt. At this point write 
displays ‘EOT’ on your recipient’s screen and exits. 

To write to a user who is logged in more than once, use the ttyname argument to indicate the appropriate 
terminal name. 

You can grant or deny other users permission to write to you by using the mesg command (default allows 
writing). Certain commands, nroff and pr( 1) in particular, don’t allow anyone to write to you while you 
are using them in order to prevent messy output. 

If write finds the character *!’ at the beginning of a line, it calls the shell to execute the rest of the line as a 
command. 

Two people can carry on a conversation by write’ mg to each other. When the other person receives the 
message indicating you are writing to him, he can then write back to you if he wishes. However, since you 
are now simultaneously typing and receiving messages, you end up with garbage on your screen unless you 
work out some sort of scheduling scheme with your partner. You might try the following conventional 
protocol: when you first write to another user, wait for him to write back before starting to send. Each per- 
son should end each message with a distinctive signal o- (for ‘over’) is standard — so that the other 

knows when to begin a reply. To end your conversation, type -oo- (for ‘over and out’) before finishing the 
conversation. 

EXAMPLE 

Here is an example of a short dialog between two people on different terminals. Two users called Horace 
and Eudora are logged in on a system called jones. To illustrate the process, both users’ screens are shown 
side-by-side: 

Eudora’s Terminal Horace’s Terminal 

Horace is staring at his screen 

jones% write horace Message from jones leudora on tty09 at 17:05 ... 

how about a squash game tonight? -o- how about a squash game tonight? -o- 

jones% write eudora 
I’m playing tiddlywinks with Carmeline -o- 
Message from jones Ihorace on tty03 at 17:06 ... 

I’m playing tiddlywinks with Carmeline -o- 

How about the beach on Sunday? -o- How about the beach on Sunday? -o- 

Sorry, I’m washing my tent that day -o- 

Sorry, I’m washing my tent that day -o- 

See you when I get back from Peru -oo- See you when I get back from Peru -oo- 
“D 

jones% EOF 

I hear rack of llama is very tasty -oo- 
“D 

I hear rack of llama is very tasty -oo- 

EOF jones% 
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FILES 

/etc/utmp 

/bin/sh 

SEE ALSO 

mesg(l), who(l), mail(l), talk(l) 


to find user 
to execute “!’ 
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NAME 

xsend, xget, enroll - secret mail 

SYNOPSIS 

xsend username 

xget 

enroll 

DESCRIPTION 

These commands implement a secure communication channel; the channel is like mail{\), but no one can 
read the messages except the intended recipient. The method embodies a public-key cryptosystem using 
knapsacks. 

To receive messages, use enroll ; it asks you for a password that you must subsequently quote in order to 
receive secret mail. 

To receive secret mail, use xget. It asks for your password, then gives you the messages. 

To send secret mail, use xsend in the same manner as the ordinary mail command. Unlike mail, xsend 
accepts only one target. A message announcing the receipt of secret mail is also sent by ordinary mail. 

FILES 

/usr/spool/secretmail/*.key keys 

/usr/spool/secretmail/ * . [0-9] messages 

SEE ALSO 

mail(l) 

BUGS 

The knapsack public-key cryptosystem is known to be breakable. 

RESTRICTIONS 

These facilities are not available on software shipped outside the U.S. 


406 


Last change: 13 March 1984 


Sun Release 3.0 



XSTR(l) 


USER COMMANDS 


XSTR(l) 


NAME 

xstr- extract strings from C programs to implement shared strings 
SYNOPSIS 

xstr [ -v ] [ -c ] [ - ] [ file ] 

DESCRIPTION 

Xstr maintains a file called strings into which strings in component parts of a large program are hashed. 
These strings are replaced with references to this common area. This serves to implement shared constant 
strings, most useful if they are also read-only. 

The command 

xstr -c name 

extracts the strings from the C source in name, replacing string references by expressions of the form 
(&xstr[number]) for some number. An appropriate declaration of xstr is prepended to the file. The result- 
ing C text is placed in the file x.c, to then be compiled. The strings from this file are placed in the strings 
data base if they are not there already. Repeated strings and strings which are suffixes of existing strings 
do not cause changes to the data base. 

After all components of a large program have been compiled a file xs.c declaring the common xstr space 
can be created by a command of the form 

xstr 

This xs.c file should then be compiled and loaded with the rest of the program. If possible, the array can be 
made read-only (shared) saving space and swap overhead. 

Xstr can also be used on a single file. A command 

xstr name 

creates files x.c and xs.c as before, without using or affecting any strings file in the same directory. 

It may be useful to run xstr after the C preprocessor if any macro definitions yield strings or if there is con- 
ditional code which contains strings which may not, in fact, be needed. Xstr reads from its standard input 
when the argument is given. An appropriate command sequence for running xstr after the C preproces- 
sor is: 

cc -E name.c | xstr -c - 
cc -c x.c 
mv x.o name.o 

Xstr does not touch the file strings unless new items are added, thus make can avoid remaking xs.o unless 
truly necessary. 

OPTIONS 

-c file Take C source text from file . 

-v Verbose: display a progress report indicating where new or duplicate strings were found. 

FILES 

strings Data base of strings 

x.c Massaged C source 

xs.c C source for definition of array ‘xstr’ 

/tmp/xs* Temp file when ‘xstr name’ doesn’t touch strings 

SEE ALSO 

mkstr(l) 

BUGS 

If a string is a suffix of another string in the data base, but the shorter string is seen first by xstr both strings 
will be placed in the data base, when just placing the longer one there will do. 
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NAME 

yacc - yet another compiler-compiler 
SYNOPSIS 

yacc [ -vd ] grammar 
DESCRIPTION 

Yacc converts a context-free grammar into a set of tables for a simple automaton which executes an LR(1) 
parsing algorithm. The grammar may be ambiguous; specified precedence mles are used to break ambigui- 
ties. 


The output file, y.tab.c, must be compiled by the C compiler to produce a function named yyparse. The 
yyparse function must be loaded with the lexical analyzer yylex, as well as main and yy error, an error han- 
dling routine. These routines must be supplied by the user; lex(l) is useful for creating lexical analyzers 
usable by yacc -produced parsers. 

OPTIONS 

-v Prepare the file y. output containing a description of the parsing tables and a report on conflicts 
generated by ambiguities in the grammar. 

-d Generate the file y.tab.h with the define statements that associate the yacc -assigned ‘token codes’ 
with the user-declared ‘token names’ so that source files other than y.tab.c can access the token 
codes. 


FILES 

y.output 

y.tab.c 

y.tab.h 

yacc.tmp, yacc.acts 
/usr/lib/yaccpar 


description of parsing tables and conflict report 

output parser 

defines for token names 

temporary files 

parser prototype for C programs 


SEE ALSO 

lex{ 1) 

LR Parsing by A. V. Aho and S. C. Johnson, Computing Surveys, June, 1974 

Yacc — Yet Another Compiler Compiler in Programming Tools for the Sun Workstation 


DIAGNOSTICS 

The number of reduce-reduce and shift-reduce conflicts is reported on the standard output; a more detailed 
report is found in the y. output file. Similarly, if some rules are not reachable from the start symbol, this is 
also reported. 

BUGS 

Because file names are fixed, at most one yacc process should be active in a given directory at a time. 
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NAME 

yes - be repetitively affirmative 
SYNOPSIS 

yes [ expletive ] 

DESCRIPTION 

Yes repeatedly outputs “y”, or if expletive is given, that is output repeatedly. Termination is by typing an 
interrupt character. 
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NAME 

ypcat - print values in a YP data base 
SYNOPSIS 

ypcat [ — k ] [ — t ] [ — d domainname ] mname 
ypcat -x 

DESCRIPTION 

ypcat prints out values in a yellow pages (YP) map specified by mname, which may be either a mapname 
or a map nickname. Since ypcat uses the YP network services, no YP server is specified. 

To look at the network-wide password database, passwd.byname , (with the nickname passwd). type in: 

ypcat passwd 

Refer to ypfiles(5) and ypserv(8) for an overview of the yellow pages. 

OPTIONS 

-k Display the keys for those maps in which the values are null or the key is not part of the value. 
(None of the maps derived from files that have an ASCII version in /etc fall into this class.) 

-t Inhibit translation of mname to mapname. For example, ypcat -t passwd will fail because there is 
no map named passwd, whereas ypcat passwd will be translated to ypcat passwd.byname. 

-d Specify a domain other that the default domain. The default domain is returned by domainname. 

-x Display the map nickname table. This lists the nicknames ( mnames ) the command knows of, and 
indicates the mapname associated with each nickname. 

SEE ALSO 

ypfiles(5), ypserv(8), ypmatch(l), domainname(8) 
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NAME 

ypmatch - print the value of one or more keys from a yp map 

SYNOPSIS 

ypmatch [ -d domain ] [ -k ] [ -t ] key . . . mname 
ypmatch -x 

DESCRIPTION 

ypmatch prints the values associated with one or more keys from the yellow pages (YP) map (database) 
specified by a mname, which may be either a mapname or an map nickname . 

Multiple keys can be specified; the same map will be searched for all . The keys must be exact values 
insofar as capitalization and length are concerned. No pattern matching is available. If a key is not 
matched, a diagnostic message is produced. 

OPTIONS 

-d Specify a domain other that the default domain. 

-k Before printing the value of a key, print the key itself, followed by a colon (’:’). This is useful 
only if the keys are not duplicated in the values, or you’ve specified so many keys that the output 
could be confusing. 

-t Inhibit translation of nickname to mapname. For example, ypmatch -t zippy passwd will fail 
because there is no map named passwd, while ypmatch zippy passwd will be translated to ypmatch 
zippy passwd.byname . 

—x Display the map nickname table. This lists the nicknames {mnames) the command knows of, and 
indicates the mapname associated with each nickname. 

SEE ALSO 

ypfiles(5), ypcat(l) 
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NAME 

ypwhich - which host is the YP server or map master? 

SYNOPSIS 

ypwhich [ -d [ domain ] [ —VI | — V2 ] [ hostname ] 
ypwhich [ — t mapname ] [ — d domain ] — m mname 
ypwhich -x 

DESCRIPTION 

ypwhich tells which YP server supplies yellow pages services to a YP client, or which is the master for a 
map. If invoked without arguments, it gives the YP server for the local machine. If hostname is specified, 
that machine is queried to find out which YP master it is using. 

Refer to ypfiles(5) and ypserv(8) for an overview of the yellow pages. 

OPTIONS 

-d Use domain instead of the default domain. 

-VI Which server is serving v.l YP protocol-speaking client processes? 

-V2 Which server is serving v.2 YP protocol client processes? 

If neither version is specified, ypwhich attempts attempts to locate the server that supplies the 
(current) v.2 services. If there is no v.2 server currently bound, ypwhich then attempts to 
locate the server supplying the v.l services. Since YP servers and YP clients are both back- 
ward compatible, the user need seldom be concerned about which version is currently in use. 

-t mapname Inhibit nickname translation; useful if there is a mapname identical to a nickname. This is 
not true of any Sun-supplied map. 

-m Find the master YP server for a map. No hostname can be specified with -m. mname can 

be a mapname, or a nickname for a map. 

-x Display the map nickname table. This lists the nicknames ( mnames ) the command knows 

of, and indicates the mapname associated with each nickname. 

SEE ALSO 

ypfiles(5), rpcinfo(8), ypset(8), ypserv(8) 
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NAME 

yppasswd - change login password in yellow pages 
SYNOPSIS 

yppasswd [name] 

DESCRIPTION 

Yppasswd changes (or installs) a password associated with the user name (your own name by default) in 
the yellow pages. The yellow pages password may be different from the one on your own machine. 

Yppasswd prompts for the old yellow pages password and then for the new one. The caller must supply 
both. The new password must be typed twice, to forestall mistakes. 

New passwords must be at least four characters long if they use a sufficiently rich alphabet and at least six 
characters long if monocase. These rules are relaxed if you are insistent enough. 

Only the owner of the name or the super-user may change a password; in either case you must prove you 
know the old password. 

SEE ALSO 

passwd(l), ypfiles(5), yppasswdd(8C) 

BUGS 

The update protocol passes all the information to the server in one rpc call, without ever looking at it. Thus 
if you type in your old password incorrectly, you will not be notified until after you have entered your new 
password. 
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NAME 

intro - introduction to games and demos 
DESCRIPTION 

This section describes games and demos in alphabetical order. 
SEE ALSO 

Games, Demos and Other Pursuits: Beginner’s Guide 
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NAME 

adventure - an exploration game 
SYNOPSIS 

/usr/games/adventure 

DESCRIPTION 

The object of the game is to locate and explore Colossal Cave, find the treasures hidden there, and bring 
them back to the building with you. The program is self-describing to a point, but part of the game is to 
discover its rules. 

To terminate a game, type ‘quit’; to save a game for later resumption, type ‘suspend’. 

BUGS 

Saving a game creates a large executable file instead of just the information needed to resume the game. 
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NAME 

arithmetic - provide drill in number facts 
SYNOPSIS 

/usr/games/arithmetic [ +-x/ ] [ range ] 

DESCRIPTION 

Arithmetic types out simple arithmetic problems, and waits for an answer to be typed in. If the answer is 
correct, it types back “Right!”, and a new problem. If the answer is wrong, it replies “What?”, and waits 
for another answer. Every twenty problems, it publishes statistics on correctness and the time required to 
answer. 

To quit the program, type an interrupt (delete). 

The first optional argument determines the kind of problem to be generated; +-x/ respectively cause addi- 
tion, subtraction, multiplication, and division problems to be generated. One or more characters can be 
given; if more than one is given, the different types of problems will be mixed in random order; default is 
+— 

Range is a decimal number; all addends, subtrahends, differences, multiplicands, divisors, and quotients 
will be less than or equal to the value of range. Default range is 10. 

At the start, all numbers less than or equal to range are equally likely to appear. If the respondent makes a 
mistake, the numbers in the problem which was missed become more likely to reappear. 

As a matter of educational philosophy, the program will not give correct answers, since the learner should, 
in principle, be able to calculate them. Thus the program is intended to provide drill for someone just past 
the first learning stage, not to teach number facts de novo . For almost all users, the relevant statistic should 
be time per problem, not percent correct 
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NAME 

backgammon - the game of backgammon 
SYNOPSIS 

backgammon [ - ] [ n r w b pr pw pb t term sfile ] 

DESCRIPTION 

Backgammon lets you play backgammon against the computer or against a ‘friend’. All commands only 
are one letter, so you don’t need to type a carriage return, except at the end of a move. Backgammon is 
mostly self documenting, so that a question mark (?) will usually get some help. If you answer ‘y’ when 
backgammon asks if you want the rules, you will get text explaining the rules of the game, some hints on 
strategy, instruction on how to use backgammon, and a tutorial consisting of a practice game against the 
computer. A description of how to use backgammon can be obtained by answering ‘y’ when it asks if you 
want instructions. The possible arguments for backgammon (most are unnecesary but some are very con- 
venient) consist of: 

n don’t ask for rules or instructions 
r player is red (implies n) 
w player is white (implies n) 
b two players, red and white (implies n) 
pr print the board before red’s turn 
pw print the board before white’s turn 
pb print the board before both player’s turn 

t term terminal is type term, uses letcltermcap, otherwise uses the TERM environment variable. 

sfile recover previously saved game from file. This can also be done by executing the saved file, that 
is, typing its name in as a command. 

Arguments may be optionally preceded by a - sign. Several arguments may be concatenated together, but 
not after ‘s’ or ‘t’ arguments, since they can be followed by an arbitrary string. Any unrecognized argu- 
ments are ignored. An argument of a lone - gets a description of possible arguments. 

If term has capabilities for direct cursor movement, backgammon ‘fixes’ the board after each move, so the 
board does not need to be reprinted, unless the screen suffers some horrendous malady. Also, any ‘p’ 
option will be ignored. 

QUICK REFERENCE 

When backgammon prompts by typing only your color, type a space or carriage return to roll, or 
d to double 

p to print the board 
q to quit 

s to save the game for later 

When backgammon prompts with ’Move:’, type 

p to print the board 

q to quit 

s to save the game 

or a move, which is a sequence of 

s-f move from s to f 

s/r move one man on s the roll r separated by commas or spaces and ending with a newline. Avail- 
able abbreviations are 
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s-fl-f2 means s-fl,fl-f2 
s/rlr2 means s/rl,s/r2 

Use ‘b’ for bar and ‘h’ for home, or 0 or 25 as appropriate. 

FILES 

/usr/games/teachgammon rules and tutorial 
/etc/termcap terminal capabilities 

BUGS 

Backgammon’ s strategy needs much work. 
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NAME 

banner - print large banner on printer 
SYNOPSIS 

/usr/games/banner [ -wn ] message ... 

DESCRIPTION 

Banner prints a large, high quality banner on the standard output. If the message is omitted, it prompts for 
and reads one line of its standard input. If-w is given, the output is scrunched down from a width of 132 
to n , suitable for a narrow terminal. If n is omitted, it defaults to 80. 

The output should be printed on a hard-copy device, up to 132 columns wide, with no breaks between the 
pages. The volume is enough that you want a printer or a fast hardcopy terminal, but if you are patient, a 
decwriter or other 300 baud terminal will do. 


BUGS 

Several ASCII characters are not defined, notably <, >, [, ], \, ', _, {, }, |, and '. Also, the characters ", ’, 
and & are funny looking (but in a useful way.) 

The -w option is implemented by skipping some rows and columns. The smaller it gets, the grainier the 
output. Sometimes it runs letters together. 
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NAME 

bed - convert to antique media 

SYNOPSIS 

/usr/games/bed text 

DESCRIPTION 

Bed converts the literal text into a form familiar to old-timers. 
SEE ALSO 

dd(l) 
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NAME 

bdemos - demonstrate Sun Monochrome Bitmap Display 

SYNOPSIS 

/usr/demo/bballs 
/usr/demo/bbounce 
/usr/demo/bdemos 
/usr/demo/bjump 
/usr/demo/bphoto file 
I usr/demo/brotcube 


DESCRIPTION 

Bdemos is a collection of simple demonstration programs for the Sun Monochrome Bitmap Display. Each 
program is briefly described below. Unless otherwise noted, each program should be terminated by typing 
the appropriate key (usually DELETE or ~C) to generate an interrupt signal. 

bballs colliding balls demo 

bbounce bouncing square demo 

bdemos a collection of demos 


This program has a menu for selection of several different demos. After typing a key to select 
a particular demo, the user may type A C to get back the menu. Type ‘q’ to quit 

bjump simulated jump to hyperspace 

bphoto file dither monochrome image file to bitmap display 

Image files suitable for display by this program are in /usr/demo/bwpix. 

brotcube black and white spinning cube 

FILES 

/usr/demo/bwpix 

SEE ALSO 

draw(6) 
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NAME 

boggle - play the game of boggle 
SYNOPSIS 

/usr/games/boggle [ + ][++] 

DESCRIPTION 

This program is intended for people wishing to sharpen their skills at Boggle (TM Parker Bros.). If you 
invoke the program with 4 arguments of 4 letters each, (e.g. “boggle appl epie moth erhd”) the program 
forms the obvious Boggle grid and lists all the words from /usr/dict/words found therein. If you invoke the 
program without arguments, it will generate a board for you, let you enter words for 3 minutes, and then 
tell you how well you did relative to /usr/dict/words. 

The object of Boggle is to find, within 3 minutes, as many words as possible in a 4 by 4 grid of letters. 
Words may be formed from any sequence of 3 or more adjacent letters in the grid. The letters may join hor- 
izontally, vertically, or diagonally. However, no position in the grid may be used more than once within 
any one word. In competitive play amongst humans, each player is given credit for those of his words 
which no other player has found. 

In interactive play, enter your words separated by spaces, tabs, or newlines. A bell will ring when there is 
2:00, 1:00, 0:10, 0:02, 0:01, and 0:00 time left. You may complete any word started before the expiration 
of time. You can surrender before time is up by hitting ’break’. While entering words, your erase character 
is only effective within the current word and your line kill character is ignored. 

Advanced players may wish to invoke the program with 1 or 2 +’s as the first argument. The first + 
removes the restriction that positions can only be used once in each word. The second + causes a position 
to be considered adjacent to itself as well as its (up to) 8 neighbors. 
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NAME 

boggletool - play a game of boggle 
SYNOPSIS 

boggletool [ number ] [ + [+]] [ 16-character string ] 

DESCRIPTION 

Boggletool allows you to play the game of Boggle (TM Parker Bros.) against the computer. The number 
argument specifies the time limit in minutes (the default is 3 minutes). If a 16 character long string is 
placed on the command line, it is interpreted as a Boggle board: the first four letters form the top row, the 
next four letters the second row, etc. If no letters are specified, a board is randomly rolled by the computer 
from a set of Boggle cubes. The +[+] argument is explained below under Advanced Play . 

PLAYING THE GAME 

Rules of the Game The object of Boggle is to find as many words as possible in a 4 by 4 grid of letters 
within a certain time limit. Words may be formed from any sequence of 3 or more adjacent letters in the 
grid. The letters may join horizontally, vertically, or diagonally. Normally, no letter in the grid may be 
used more than once in a word (see Advanced Play for exceptions). 

Playing the Game When invoked, boggletool displays a grid of letters and an hourglass. To enter words, 
simply type in lower case letters to spell the word you want. Use any whitespace (space, tab, or newline) 
to finish a word. To correct mistakes you make, use backspace or DEL to delete the last character, or use 
CTRL-U to delete an entire word. 

Boggletool verifies that words you enter are both in the grid and are valid English words. If you type in a 
character which would form a word which is not in the grid, the display will flash and the character you 
typed will not be echoed. When you type any whitespace to end the current word, boggletool will verify 
that the word is three or more letters long and that it appears in the dictionary. If the word you typed is ille- 
gal for either reason, the display will flash and you will have to either erase the word or change it. If you 
try to enter a valid word which you have already entered, the display will flash and the previous occurance 
of the word will be highlighted. Again, you will have to erase the word before continuing. 

As you enter words, the "sand" in the hourglass will fall. At the end of the time limit, the display will flash 
and you will no longer be allowed to enter words. After a moment, the computer will display two lists of 
words: the words you found, and other words which also appear in the grid. To play another game, just 
type any capital letter (or use the pop-up menu). 

Using the Menu The pop-up menu is invoked by pressing the right button. There are four items in it, and 
they work as follows. Restart Game causes boggletool to create a new board, reset the timer, and allow 
you to start from scratch. Restart Timer allows you to cheat by reseting the hourglass timer to zero. Give 
Up causes boggletool to end the game and print the results immediately. Quit allows you to quit running 
the boggletool program. A prompt appears asking you to confirm the quit; when it does, click the left but- 
ton to quit or the right button to abort the quit. 

Advanced Play There are two options for advanced players. If a single + appears on the command line, 
letters in the grid may be reused. If two +’s are on the command line, letters may also be considered adja- 
cent to themselves as well as to their neighbors. Although it is far easier to find words with these two 
options, there are also many more possible words in the grid and it is therefore difficult to find them all. 


FILES 

/usr/games/boggledict dictionary file for computer’s words 


424 


Last change: 14 May 1985 


Sun Release 3.0 



BROTCUBE ( 6 ) 


GAMES AND DEMOS 


BROTCUBE (6) 


NAME 

brotcube - rotate a simple cube 

SYNOPSIS 

/usr/demo/brotcube 

DESCRIPTION 

Brotcube rotates a skeletal outline of a cube consisting of 14 vectors. Using the SunCore Graphics Pack- 
age, a 3-D projection is drawn on the Sun Monochrome Bitmap Display. Each rotation consists of 100 
views. 

This program gives an indication of the performance of the SunCore Graphics Package. 

Type ‘q’ to exit the program. 
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NAME 

bsuncube - view 3-D Sun logo 

SYNOPSIS 

/ usr/demo/bsuncube 

DESCRIPTION 

Bsuncube allows the user to view a cube from various positions with hidden faces removed. The faces of 
the cube consist of the Sun logo. The viewing position is selected using the mouse. Using the SunCore 
Graphics Package, a 3-D projection is drawn on the Sun Monochrome Bitmap Display. 

The program operates in two modes: DisplayObject mode and SelectView mode. The program starts in 
DisplayObject mode. 

DisplayObject: The cube is displayed in 3-D perspective with hidden faces removed. Type "q" while in 
this mode to exit the program. Hit mouse button 3 to switch to SelectView mode. 

SelectView: Schematic projections of the outline of the cube are shown and the mouse is used to select a 
viewing position. Use button 1 to set x and button 2 to set y in the Front View. Use button 2 to set z in the 
Top View. Hit button 3 to switch to DisplayObject mode. 

The view shown in DisplayObject mode is drawn using the conventions that the viewer is always looking 
from the viewing position toward the center of the cube and that the positive y axis on the screen is the pro- 
jection of the positive y axis in 3-D cube coordinates. 
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NAME 

canfield, cfscores - the solitaire card game canfield 
SYNOPSIS 

/ usr/games/canfield 
/usr/games/cfscores 

DESCRIPTION 

If you have never played solitaire before, it is recommended that you consult a solitaire instruction book. In 
Canfield, tableau cards may be built on each other downward in alternate colors. An entire pile must be 
moved as a unit in building. Top cards of the piles are available to be able to be played on foundations, but 
never into empty spaces. 

Spaces must be filled from the stock. The top card of the stock also is available to be played on foundations 
or built on tableau piles. After the stock is exhausted, tableau spaces may be filled from the talon and the 
player may keep them open until he wishes to use them. 

Cards are dealt from the hand to the talon by threes and this repeats until there are no more cards in the 
hand or the player quits. To have cards dealt onto the talon the player types ’ht’ for his move. Foundation 
base cards are also automatically moved to the foundation when they become available. 

The command ’c’ causes canfield to maintain card counting statistics on the bottom of the screen. When 
properly used this can greatly increase ones chances of winning. 

The rules for betting are somewhat less strict than those used in the official version of the game. The initial 
deal costs $13. You may quit at this point or inspect the game. Inspection costs $13 and allows you to 
make as many moves as is possible without moving any cards from your hand to the talon, (the initial deal 
places three cards on the talon; if all these cards are used, three more are made available.) Finally, if the 
game seems interesting, you must pay the final installment of $26. At this point you are credited at the rate 
of $5 for each card on the foundation; as the game progresses you are credited with $5 for each card that is 
moved to the foundation. Each run through the hand after the first costs $5. The card counting feature 
costs $1 for each unknown card that is identified. If the information is toggled on, you are only charged for 
cards that became visible since it was last turned on. Thus the maximum cost of information is $34. Play- 
ing time is charged at a rate of $1 per minute. 

With no arguments, the program cfscores prints out the current status of your canfield account. If a user 
name is specified, it prints out the status of their canfield account If the -a flag is specified, it prints out 
the canfield accounts for all users that have played the game since the database was set up. 

FILES 

/usr/games/canfield the game itself 

/usr/games/cfscores the database printer 

/usr/games/lib/cfscores the database of scores 

BUGS 

It is impossible to cheat 
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NAME 

chase - Try to escape to killer robots 
SYNOPSIS 

/usr/games/chase [ nrobots ] [ nfences ] 

DESCRIPTION 

The object of the game chase is to move around inside of the box on the screen without getting eaten by the 
robots chasing and without running into anything. 

If a robot runs into another robot while chasing you, they crash and leave a junk heap. If a robot runs into a 
fence, it is destroyed. 

If you can survive until all the robots are destroyed, you have won! 

If you do not specify either nrobots or nfences, chase will prompt you for them. 
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NAME 

chess - the game of chess 

SYNOPSIS 

/usr/games/chess 

DESCRIPTION 

Chess is a computer program that plays class D chess. Moves may be given either in standard (descriptive) 
notation or in algebraic notation. The symbol V is used to specify check; ‘o-o’ and ‘o-o-o’ specify cas- 
tling. To play black, type ‘first’; to print the board, type an empty line. 

Each move is echoed in the appropriate notation followed by the program’s reply. 

DIAGNOSTICS 

The most cryptic diagnostic is ‘eh?’ which means that the input was syntactically incorrect. 

FILES 

/usr/games/lib/chess.book book of opening moves 

BUGS 

Pawns may be promoted only to queens. 
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NAME 

chesstool - window-based front-end to chess program 
SYNOPSIS 

chesstool [ chess _program ] 

DESCRIPTION 

Chesstool is a window-based front-end to the chess (6) program. Used without options, chesstool uses 
lusrl games! chess ; you can designate any alternate program which uses the same command syntax as 
chess (6) with the chess _program argument. 

When chesstool starts up, it displays a large window with three subwindows. The first subwindow displays 
messages — “Illegal move”, for example. The second subwindow is an options subwindow; options are 
described below. The final subwindow is a chessboard display with white and black pieces and two 
(advisory only) timekeeping clocks. 

Make your moves with the mouse: select a piece by positioning the arrow cursor over the piece and press- 
ing the left mouse button down, then drag the piece to the destination square, and release the button. The 
cursor will then turn to an hourglass icon while the system plays. 

Options in the options subwindow may be selected with either the left or middle mouse buttons. These 
options are: 


Last Play 
Undo 

Machine White 
Human White 
Quit 


Show the last play made. 

Undo your last move and the machine’s response. 

Once the game is over, it is not possible to restart it, so undo will update the board, 
but the game cannot be continued from that position. 

Start a new game with the machine playing white. 

Start a new game with the machine playing black. 

Exit from chesstool. 


Flash Flash when the machine has completed its move. 

When this command is selected, a check mark will appear next to the word Flash. 
In flash mode, if chesstool is open, the piece moved by the system on its play will 
flash until you make your move. If chesstool is iconic, the entire icon will flash 
when the machine has made its move. Thus you can ‘Close’ chesstool and be alerted 
when it’s your turn to move. To turn flash mode off, select flash again. 


There are two moves which are special: castling and capturing a pawn en passant. To castle, move the 
king only. The position of the rook will automatically be updated. Since the king moves two squares when 
castling, the move is unambiguous. To capture en passant, move the pawn to the square occupied by the 
opposing pawn which will be captured. 

SEE ALSO 

chess(6) 
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NAME 

ching - the book of changes and other cookies 
SYNOPSIS 

/usr/games/ching [ hexagram ] 

DESCRIPTION 

The I Ching or Book of Changes is an ancient Chinese oracle that has been in use for centuries as a source 
of wisdom and advice. 

The text of the oracle (as it is sometimes known) consists of sixty-four hexagrams, each symbolized by a 

particular arrangement of six straight ( ) and broken (- -) lines. These lines have values ranging from 

six through nine, with the even values indicating the broken lines. 

Each hexagram consists of two major sections. The Judgement relates specifically to the matter at hand 
(E.g., “It furthers one to have somewhere to go.”) while the Image describes the general attributes of the 
hexagram and how they apply to one’s own life (“Thus the superior man makes himself strong and untir- 
ing.”). 

When any of the lines has the value six or nine, it is a moving line; for any such line there is an appended 
judgement which becomes significant Furthermore, the moving lines are inherently unstable and change 
into their opposites; a second hexagram (and thus an additional judgement) is formed. 

Normally, one consults the oracle by fixing the desired question firmly in mind and then casting a set of 
changes (lines) using yarrow-stalks or tossed coins. The resulting hexagram will be the answer to the 
question. 

Using an algorithm suggested by S. C. Johnson, the UNIX oracle simply reads a question from the stan- 
dard input (up to an EOF) and hashes the individual characters in combination with the time of day, pro- 
cess id and any other magic numbers which happen to be lying around the system. The resulting value is 
used as the seed of a random number generator which drives a simulated coin-toss divination. The answer 
is then piped through nroff for formatting and will appear on the standard output. 

For those who wish to remain steadfast in the old traditions, the oracle will also accept the results of a per- 
sonal divination using, for example, coins. To do this, cast the change and then type the resulting line 
values as an argument. 

The impatient modem may prefer to settle for Chinese cookies; try fortune (6). 

SEE ALSO 

It furthers one to see the great man. 

DIAGNOSTICS 

The great prince issues commands, 

Founds states, vests families with fiefs. 

Inferior people should not be employed. 

BUGS 

Waiting in the mud 

Brings about the arrival of the enemy. 

If one is not extremely careful, 

Somebody may come up from behind and strike him. 

Misfortune. 
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NAME 

colordemos - demonstrate Sun Color Graphics Display 

SYNOPSIS 

/usr/demo/cballs 
/ usr/demo/cdraw 
/usr/demo/cphoto file 
/usr/demo/cpipes 
/usr/demo/cshowmap file 
/usr/demo/csnow 
/usr/demo/csuncube 
/usr/demo/csunlogo 
/usr/demo/cvlsi 

DESCRIPTION 

Colordemos is a collection of simple demonstration programs for the Sun Color Graphics Display. Each 
program is briefly described below. To exit each program, send an interrupt signal by typing the appropri- 
ate key (usually CONTROL C). 

cballs colliding balls on color display 

cdraw draw on the color display; see draw (6) for an explanation of how to use cdraw. 

cphoto file display dithered color file on color display. Files suitable for display are in lusr/demo/colorpix. 

cpipes colliding pipes on color display 

cshowmap file 

display maps. Files suitable for display are in lusrldemol segments. 
csnow color kaleidoscope 
csuncube multicolored Sun logo 
csunlogo shaded Sun logo 
cvlsi color vlsi layout demo 

FILES 

/usr/demo/colorpix 

/usr/demo/segments 
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NAME 

cribbage - the card game cribbage 
SYNOPSIS 

/usr/games/cribbage [ -req ] name ... 

DESCRIPTION 

Cribbage plays the card game cribbage, with cribbage playing one hand and the user the other. Cribbage 
initially asks the user if the rules of the game are needed - if so, cribbage displays the appropriate section 
from According to Hoyle with more(l). 

OPTIONS 

-e Provide an explanation of the correct score when the player makes mistakes scoring his hand or 
crib. This is especially useful for beginning players. 

-q Print a shorter form of all messages - this is only recommended for users who have played the 
game without specifying this option. 

-r Instead of asking the player to cut the deck, cribbage will randomly cut the deck. 

PLAYING CRIBBAGE 

Cribbage first asks the player whether he wishes to play a short game (“once around”, to 61) or a long 
game (“twice around”, to 121). A response of ‘s’ results in a short game, any other response plays a long 
game. 

At the start of the first game, cribbage asks the player to cut the deck to determine who gets the first crib. 
The user should respond with a number between 0 and 51, indicating how many cards down the deck is to 
be cut. The player who cuts the lower ranked card gets the first crib. If more than one game is played, the 
loser of the previous game gets the first crib in the current game. 

For each hand, cribbage first prints the player’s hand, whose crib it is, and then asks the player to discard 
two cards into the crib. The cards are prompted for one per line, and are typed as explained below. 

After discarding, cribbage cuts the deck (if it is the player’s crib) or asks the player to cut the deck (if it’s 
its crib); in the later case, the appropriate response is a number from 0 to 39 indicating how far down the 
remaining 40 cards are to be cut. 

After cutting the deck, play starts with the non-dealer (the person who doesn’t have the crib) leading the 
first card. Play continues, as per cribbage, until all cards are exhausted. Cribbage keeps track of the scor- 
ing of all points and the total of the cards on the table. 

After play, the hands are scored. Cribbage requests the player to score his hand (and the crib, if it is his) 
by printing out the appropriate cards (and the cut card enclosed in brackets). Play continues until one 
player reaches the game limit (61 or 121). 

A carnage return when a numeric input is expected is equivalent to typing the lowest legal value; when 
cutting the deck this is equivalent to choosing the top card. 

SPECIFYING CARDS 

Cards are specified as rank followed by suit. The ranks may be specified as one of a, 2, 3, 4, 5, 6, 7, 8, 9, 
t, j, q, and k, or alternatively, one of ace, two, three, four, five, six, seven, eight, nine, ten, jack, queen, 
and king. Suits may be specified as s, h, d, and c, or alternatively as spades, hearts, diamonds, and clubs. 
A card may be specified as rank suit, or rank of suit. If the single letter rank and suit designations are 
used, the space separating the suit and rank may be left out. Also, if only one card of the desired rank is 
playable, typing the rank is sufficient. For example, if your hand was 2h, 4d, 5c, 6h, jc, kd and you 
wanted to discard the king of diamonds, you could type any of k, king, kd, k d, k of d, king d, king of d, 
k diamonds, k of diamonds, king diamonds, or king of diamonds. 

FILES 

/usr/games/cribbage 
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NAME 

draw - interactive graphics drawing 

SYNOPSIS 

/ usr/demo/bdraw 
/usr/demo/cdraw 

DESCRIPTION 

The draw programs are menu-driven programs which use the mouse, keyboard, bitmap display and option- 
ally the color display to draw objects, drag them around, save them on disk, and so on. Bdraw is the draw 
program for the black and white display and cdraw is the program for driving the color display. 

The main menu items are selected by moving the mouse cursor and pressing the left mouse button. To 
redraw the display, point at the left edge of the main menu box and press the left button. The main menu 
items are: 

New Seg xlate 

Open a new translatable segment. A segment is a collection of attributes and primitives (lines, 
text, polygons, etc.). A translatable segment may subsequently be positioned. 

New Seg xform 

Open a new transformable segment A transformable segment may subsequently be rotated, 
scaled, or positioned. 

Delete Seg To delete a segment, point at any primitive in the segment and press the left button. 

Lines To add line primitives to the currently open segment, position cursor, press the left button, ... 
press right button to quit. 

Polygon To add a polygon primitive to the currently open segment, position the cursor, press the left 
button, . . . press the right button to terminate the boundary definition. Polygons are filled with 
the current fill attribute. 

Raster To add a raster primitive to the currently open segment, position the cursor, press the left but- 
ton to reposition the box, adjust the box by moving the mouse, press the right button to create 
the raster primitive comprising the boxed bitmap. A ‘rasterfile’ is also created on disk for 
hardcopy purposes (see lusrlincludelrasterfile.h). This ‘rasterfile’ file may be spooled to a 
Versatec printer/plotter for hardcopy after exiting from the draw program. The command to 
do this is lpr -v rasterfile. 

Text To add a text primitive to the currently open segment, position cursor, press left button, type 
the text string at the keyboard (back space works), hit return. Text is drawn with the current 
text attributes. 

Marker To add marker primitives to the currently open segment, position cursor, press the left button 
to place marker, ... press the right button to quit. 

Position To position a segment, point at any primitive in the segment, press left button, position the seg- 
ment, press right button to quit. 

Rotate To rotate a transformable segment, point at any primitive in the segment, press left button, 
move mouse to rotate, press right button to quit. 

Scale To scale a transformable segment, point at any primitive in the segment, press the left button, 
move mouse to scale in x or y, press right button to quit. 

Attributes This item brings up the attribute menu. To select an attribute such as text font, region fill tex- 
ture (color), linestyle, or line width, point at the item and press the left button. Point at the left 
edge of the menu box to quit. 

Save Seg To save a segment on a disk file, point at the segment, press the left button, type the disk file 
name, hit return. 

Restore Seg 


434 


Last change: 8 March 1984 


Sun Release 3.0 



DRAW ( 6 ) 


GAMES AND DEMOS 


DRAW ( 6 ) 


To restore a previously saved segment from disk, type file name, hit return. 

Exit Exit the draw program. 

BUGS 

Rasters and raster text do not scale or rotate. If segments completely overlap, only the last one drawn may 
be picked by pointing with the mouse. This also applies to the menu segments! Therefore, don’t cover 
them up with polygons. If aborted with your interrupt character, you must give the ‘reset’ command to turn 
keyboard echo back on and to reset -cbreak. Therefore, use the Exit item in the main menu to exit the pro- 
gram. 
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NAME 

fish - play “Go Fish” 

SYNOPSIS 

/usr/games/fish 

DESCRIPTION 

Fish plays the game of “Go Fish”, a children’s card game. The object is to accumulate ‘books’ of 4 cards 
with the same face value. The players alternate turns; each turn begins with one player selecting a card 
from his hand, and asking the other player for all cards of that face value. If the other player has one or 
more cards of that face value in his hand, he gives them to the first player, and the first player makes 
another request Eventually, the first player asks for a card which is not in the second player’s hand: he 
replies ‘GO FISH!’ The first player then draws a card from the ‘pool’ of undealt cards. If this is the card 
he had last requested, he draws again. When a book is made, either through drawing or requesting, the 
cards are laid down and no further action takes place with that face value. 

To play the computer, simply make guesses by typing a, 2, 3, 4, 5, 6, 7, 8, 9, 10, j, q, or k when asked. Hit- 
ting return gives you information about the size of my hand and the pool, and tells you about my books. 
Saying ‘p’ as a first guess puts you into ‘pro’ level; the default is pretty dumb. 
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NAME 

fortune - print a random, hopefully interesting, adage 
SYNOPSIS 

/usr/games/fortune [ - ] [ -wsla ] 

DESCRIPTION 

Fortune with no arguments prints out a random adage. The flags mean: 

-w Waits before termination for an amount of time calculated from the number of characters in the mes- 
sage. This is useful if it is executed as part of the logout procedure to guarantee that the message can 
be read before the screen is cleared. 

-s Short messages only. 

-1 Long messages only. 

-a Choose from either list of adages. 

FILES 

/usr/games/lib/fortunes.dat 
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NAME 

gammontool - play a game of backgammon 

SYNOPSIS 

gammontool [ path ] 

DESCRIPTION 

Gammontool paints a backgammon board on the screen, and then lets you play against the computer. It 
must be run in SunWindows. The optional path argument specifies an alternate move-generating program, 
which must be specially designed to run with gammontool. 

The game has three subwindows: an option window on top, a message window in the middle, and a large 
board on the bottom. The buttons in the option window are used to restart, double, etc. The message win- 
dow has two lines: the first tells whose turn it is, and the second displays any errors that occur. 

The initial roll. To start the game, roll the dice to determine who goes first. Move the mouse arrow onto 
the board and click the left button. One die appears on each side of the board: the die on the left is yours, 
and the die on the right is the computer’s. If your roll is greater, then you move; if not, the computer 
makes a move. 

Making your move. When it is your turn, “Your move” appears in the message window. Place the mouse 
over any piece of your color, and click the left button. While holding down the button, move the mouse to 
drag the piece; the piece follows the mouse until you release the button. The tool checks each move and 
does not allow illegal moves. When you have made as many moves as you can, the computer takes its 
turn; after it finishes, you may either roll again, or double. 

Doubling. To double, click the Double button in the option window and wait for the computer’s response. 
If the computer doubles you, a message is displayed and you must answer with the Accept Double or 
Refuse Double buttons. The Forfeit button can also be used to refuse a double. If the game is doubled, a 
doubling cube with the proper value is displayed on the bar strip. If the number is facing up, then you may 
double next. If the number is upside down, it is the computer’s turn to double. 

Other buttons. If you want to change your move before you have finished it, use the Redo Move or 
Redo Entire Move buttons in the option window. Redo Entire Move replaces all of the pieces you have 
moved so that you can redo them all. Redo Move only replaces the last piece you moved, so it is useful 
when you roll doubles and want to redo only the last piece you moved. Note that once you have made all 
of the moves your roll permits, play passes immediately to the computer, so you cannot redo the very last 
move. The Show Last Move button allows you to see the last move again. 

Leaving the game. If you want to quit playing backgammon, use the Quit button. If you want to forfeit the 
game, use the Forfeit button. The computer penalizes you by taking a certain number of points, but the 
program does not terminate. 

To play another game after winning, losing, or forfeiting, click the New Game button. To change the color 
of your pieces, click the mouse button while pointing at either the White or Black checkboxes. You may 
change colors at any time, even in the middle of a game. Changing colors in the middle of a game does not 
mean that you trade places with the computer; your pieces stay where they are, but they are repainted with 
the new color. Your pieces always move from the top right to the bottom right of the board, regardless of 
your color. As an additional cue as to your color, your dice are always displayed on the left half of the 
board. 

Log file. If a there is a gammonlog file your home directory, gammontool keeps a log of the games played. 
Each move and double gets recorded, along with the winners and accumulated scores. 

FILES 

'/gammonlog log of games played 

BUGS 

The default strategy used by the computer is very poor. 
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If a single move uses more than one die (for instance if you roll 5, 6 and move 1 1 spaces without touching 
down in the middle) it is unpredictable where the program will make the piece touch down. This may be 
important if there is a blot on one of these middle points. The program will always make the move if possi- 
ble, but if two midpoints would work and there is a blot on one of them, it is much better to explicitly hit 
the blot and then move the piece the rest of the way. 
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NAME 

hack - replacement for rogue 
SYNOPSIS 

hack [ -d hackdir ] [ -s all | player ... ] 

DESCRIPTION 

Hack is a display-oriented dungeons & dragons type game. Both display and command structure resemble 
rogue, although hack has twice as many monster types and requires three times as much memory. 

Normally hack looks in lusrl gameslliblhackdir for the files listed below; this directory can be changed with 
the -d option. The -s option permits you to search the player record. Given the keyword all, hack lists all 
players; given the login name of a player, it lists all scores of that player. 

FILES 

record top 100 list (start with an empty file) 
news changes or bugs (start with no news file) 
data information about objects and monsters 
help introductory information (no doubt outdated) 
hh compacted version of help 

perm empty file used for locking 

rumors texts for fortune cookies 
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NAME 

hangman - Computer version of the game hangman 
SYNOPSIS 

/usr/games/hangman 

DESCRIPTION 

In hangman, the computer picks a word from the on-line word list and you must try to guess it The com- 
puter keeps track of which letters have been guessed and how many wrong guesses you have made on the 
screen in a graphic fashion. 

FILES 

/usr/dict/words On-line word list 
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NAME 

life - John Conway’s game of life 

SYNOPSIS 

life 

DESCRIPTION 

Life is a program that plays John Conway’s game of life. It only runs under suntools( 1). 

When invoked, life will display a window with a small control panel at the top, and a large drawing area at 
the bottom. You can create pieces in the drawing area with the left button, and erase them with the middle 
button. When you select run in the control panel, the pieces will begin to evolve, and the drawing region 
will update itself at a speed controlled by the slider labeled with fast and slow. Life keeps track of all the 
pieces even if they are not visible. The scroll bars surrounding the drawing region can be used to see 
pieces that have moved out of view. There are some standard patterns that can be drawn by popping up a 
menu in the drawing subwindow. 

The meaning of the items in the first row of the control panel (from left to right) are as follows. If you 
click on the picture which looks like a tic-tac-toe board, a grid will appear in the drawing region. If you 
click on mode, the mode will change from run mode (where the pieces update continuously) to step mode 
(where an update is only done when you click on the step label). The button marked clear will clear the 
drawing region and the one marked quit causes the tool to exit. To the right of the quit button is a counter 
that records the generation number. The second row contains two sliders. The first controls the update 
speed when in run mode, the second controls the size of the pieces. 
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NAME 

mille - play Mille Bomes 
SYNOPSIS 

/usr/games/mille [ file ] 

DESCRIPTION 

Mille plays a two-handed game reminiscent of the Parker Brother’s game of Mille Bomes with you. The 
rules are described below. If a file name is given on the command line, the game saved in that file is 
started. 

When a game is started up, the bottom of the score window will contain a list of commands. They are: 

P Pick a card from the deck. This card is placed in the ‘P’ slot in your hand. 

D Discard a card from your hand. To indicate which card, type the number of the card in the hand 

(or “P” for the just-picked card) followed by a carriage-return or space. The carriage-return or 
space is required to allow recovery from typos which can be very expensive, like discarding 
safeties. 

U Use a card. The card is again indicated by its number, followed by a carriage-return or space. 

O Toggle ordering the hand. By default off, if turned on it will sort the cards in your hand appropri- 

ately. This is not recommended for the impatient on slow terminals. 

Q Quit the game. This will ask for confirmation, just to be sure. Hitting <DELETE> (or 
<RUBOUT>) is equivalent. 

S Save the game in a file. If the game was started from a file, you will be given an opportunity to 
save it on the same file. If you don’t wish to, or you did not start from a file, you will be asked for 
the file name. If you type a carriage-return without a name, the save will be terminated and the 
game resumed. 

R Redraw the screen from scratch. The command 'L (control ‘L’) will also work. 

W Toggle window type. This switches the score window between the startup window (with all the 

command names) and the end-of-game window. Using the end-of-game window saves time by 
eliminating the switch at the end of the game to show the final score. Recommended for hackers 
and other miscreants. 

If you make a mistake, an error message will be printed on the last line of the score window, and a bell will 
beep. 

At the end of each hand or game, you will be asked if you wish to play another. If not, it will ask you if 
you want to save the game. If you do, and the save is unsuccessful, play will be resumed as if you had said 
you wanted to play another hand/game. This allows you to use the “S” command to reattempt the save. 
(The game itself is a product of Parker Brothers, Inc.) 

SEE ALSO 

curses(3X) 

CARDS 

Here is some useful information. The number in brackets after the card name is the number of that card in 
the deck: 
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RULES 


Hazard Repair 


Safety 


Out of Gas [2] 
Flat Tire [2] 
Accident [2] 
Stop [4] 

Speed Limit [3] 


Gasoline [6] 
Spare Tire [6] 
Repairs [6] 

Go [14] 

End of Limit [6] 


Extra Tank [1] 
Puncture Proof [1] 
Driving Ace [1] 
Right of Way [1] 


25 - [10], 50 - [10], 75 - [10], 100 - [12], 200 - [4] 


Object: The point of game is to get a total of 5000 points in several hands. Each hand is a race to put 
down exactly 700 miles before your opponent does. Beyond the points gained by putting down milestones, 
there are several other ways of making points. 

Overview: The game is played with a deck of 101 cards. Distance cards represent a number of miles trav- 
eled. They come in denominations of 25, 50, 75, 100, and 200. When one is played, it adds that many 
miles to the player’s trip so far this hand. Hazard cards are used to prevent your opponent from putting 
down Distance cards. With the exception of the speed limit card, they can only be played if your opponent 
has a Go card on top of the Battle pile. The cards are Out of Gas, Accident, Flat Tire, Speed Limit, and 
Stop. Remedy cards fix problems caused by Hazard cards played on you by your opponent. The cards are 
Gasoline, Repairs, Spare Tire, End of Limit, and Go. Safety cards prevent your opponent from putting 
specific Hazard cards on you in the first place. They are Extra Tank, Driving Ace, Puncture Proof, and 
Right of Way, and there are only one of each in the deck. 

Board Layout: The board is split into several areas. From top to bottom, they are: SAFETY AREA (unla- 
beled): This is where the safeties will be placed as they are played. HAND: These are the cards in your 
hand. BATTLE: This is the Battle pile. All the Hazard and Remedy Cards are played here, except the 
Speed Limit and End of Limit cards. Only the top card is displayed, as it is the only effective one. SPEED: 
The Speed pile. The Speed Limit and End of Limit cards are played here to control the speed at which the 
player is allowed to put down miles. MILEAGE: Miles are placed here. The total of the numbers shown 
here is the distance traveled so far. 

Play: The first pick alternates between the two players. Each turn usually starts with a pick from the deck. 
The player then plays a card, or if this is not possible or desirable, discards one. Normally, a play or dis- 
card of a single card constitutes a turn. If the card played is a safety, however, the same player takes 
another turn immediately. 

This repeats until one of the players reaches 700 points or the deck runs out. If someone reaches 700, they 
have the option of going for an Extension, which means that the play continues until someone reaches 1000 
miles. 

Hazard and Remedy Cards: Hazard Cards are played on your opponent’s Battle and Speed piles. 
Remedy Cards are used for undoing the effects of your opponent’s nastyness. 

Go (Green Light) must be the top card on your Battle pile for you to play any mileage, unless you have 
played the Right of Way card (see below). 

Stop is played on your opponent’s Go card to prevent them from playing mileage until they play a Go 
card. 

Speed Limit is played on your opponent’s Speed pile. Until they play an End of Limit they can only 
play 25 or 50 mile cards, presuming their Go card allows them to do even that 

End of Limit is played on your Speed pile to nullify a Speed Limit played by your opponent. 

Out of Gas is played on your opponent’s Go card. They must then play a Gasoline card, and then a Go 
card before they can play any more mileage. 

Flat Tire is played on your opponent’s Go card. They must then play a Spare Tire card, and then a Go 
card before they can play any more mileage. 

Accident is played on your opponent’s Go card. They must then play a Repairs card, and then a Go 
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card before they can play any more mileage. 

Safety Cards: Safety cards prevent your opponent from playing the corresponding Hazard cards on you for 
the rest of the hand. It cancels an attack in progress, and always entitles the player to an extra turn. 

Right of Way prevents your opponent from playing both Stop and Speed Limit cards on you. It also acts 
as a permanent Go card for the rest of the hand, so you can play mileage as long as there is not a Hazard 
card on top of your Battle pile. In this case only, your opponent can play Hazard cards directly on a 
Remedy card besides a Go card. 

Extra Tank When played, your opponent cannot play an Out of Gas on your Battle Pile. 

Puncture Proof When played, your opponent cannot play a Flat Tire on your Battle Pile. 

Driving Ace When played, your opponent cannot play an Accident on your Battle Pile. 

Distance Cards: Distance cards are played when you have a Go card on your Battle pile, or a Right of 
Way in your Safety area and are not stopped by a Hazard Card. They can be played in any combination 
that totals exactly 700 miles, except that you cannot play more than two 200 mile cards in one hand. A 
hand ends whenever one player gets exactly 700 miles or the deck runs out. In that case, play continues 
until neither someone reaches 700, or neither player can use any cards in their hand. If the trip is com- 
pleted after the deck runs out, this is called Delayed Action. 

Coup Four£: This is a French fencing term for a counter-thrust move as part of a parry to an opponents 
attack. In Mille Bomes, it is used as follows: If an opponent plays a Hazard card, and you have the 
corresponding Safety in your hand, you play it immediately, even before you draw. This immediately 
removes the Hazard card from your Battle pile, and protects you from that card for the rest of the game. 
This gives you more points (see “Scoring” below). 

Scoring: Scores are totaled at the end of each hand, whether or not anyone completed the trip. The terms 
used in the Score window have the following meanings: 

Milestones Played: Each player scores as many miles as they played before the trip ended. 

Each Safety: 100 points for each safety in the Safety area. 

All 4 Safeties: 300 points if all four safeties are played. 

Each Coup Four£: 300 points for each Coup Foure accomplished. 

The following bonus scores can apply only to the winning player. 

Trip Completed: 400 points bonus for completing the trip to 700 or 1000. 

Safe Trip: 300 points bonus for completing the trip without using any 200 mile cards. 

Delayed Action: 300 points bonus for finishing after the deck was exhausted. 

Extension: 200 points bonus for completing a 1000 mile trip. 

Shut-Out: 500 points bonus for completing the trip before your opponent played any mileage cards. 

Running totals are also kept for the current score for each player for the hand (Hand Total), the game 
(Overall Total), and number of games won (Games). 
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NAME 

monop - Monopoly game 
SYNOPSIS 

/usr/games/monop [ file ] 

DESCRIPTION 

Monop is reminiscent of the Parker Brother’s game Monopoly, and monitors a game between 1 to 9 users. 
It is assumed that the rules of Monopoly are known. The game follows the standard rules, with the excep- 
tion that, if a property would go up for auction and there are only two solvent players, no auction is held 
and the property remains unowned. 

The game, in effect, lends the player money, so it is possible to buy something which you cannot afford. 
However, as soon as a person goes into debt, he must “fix the problem”, i.e., make himself solvent, before 
play can continue. If this is not possible, the player’s property reverts to his debtee, either a player or the 
bank. A player can resign at any time to any person or the bank, which puts the property back on the 
board, unowned. 

Any time that the response to a question is a string, e.g., a name, place or person, you can type *?’ to get a 
list of valid answers. It is not possible to input a negative number, nor is it ever necessary. 

A Summary of Commands'. 

quit: quit game: This allows you to quit the game. It asks you if you’re sure. 

print: print board: This prints out the current board. The columns have the following meanings 

(column headings are the same for the where, own holdings, and holdings commands): 

Name The first ten characters of the name of the square 

Own The number of the owner of the property. 

Price The cost of the property (if any) 

Mg This field has a ‘ * ’ in it if the property is mortgaged 

# If the property is a Utility or Railroad, this is the number of such owned by the owner. 
If the property is land, this is the number of houses on it 

Rent Current rent on the property. If it is not owned, there is no rent 

where: where players are: Tells you where all the players are. A indicates the current player. 

own holdings: 

List your own holdings, i.e . , money, get-out-of-j ail-free cards, and property. 

holdings: holdings list: Look at anyone’s holdings. It will ask you whose holdings you wish to look at. 
When you are finished, type “done”. 

shell: shell escape: Escape to a shell. When the shell dies, the program continues where you left off. 

mortgage: mortgage property: Sets up a list of mortgageable property, and asks which you wish to mort- 
gage. 

unmortgage: 

unmortgage property: Unmortgage mortgaged property. 

buy: buy houses: Sets up a list of monopolies on which you can buy houses. If there is more than 

one, it asks you which you want to buy for. It then asks you how many for each piece of pro- 
perty, giving the current amount in parentheses after the property name. If you build in an 
unbalanced manner (a disparity of more than one house within the same monopoly), it asks 
you to re-input things. 

sell: sell houses: Sets up a list of monopolies from which you can sell houses, it operates in an 
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card: 

pay: 

trade: 

resign: 

save: 

restore: 

roll: 


analogous manner to buy 

card for jail: Use a get-out-of-jail-free card to get out of jail. If you’re not in jail, or you don’t 
have one, it tells you so. 

pay for jail: Pay $50 to get out of jail, from whence you are put on Just Visiting. Difficult to 
do if you’re not there. 

This allows you to trade with another player. It asks you whom you wish to trade with, and 
then asks you what each wishes to give up. You can get a summary at the end, and, in all 
cases, it asks for confirmation of the trade before doing it 

Resign to another player or the bank. If you resign to the bank, all property reverts to its virgin 
state, and get-out-of-jail free cards revert to the deck. 

save game: Save the current game in a file for later play. You can continue play after saving, 
either by adding the file in which you saved the game after the monop command, or by using 
the restore command (see below). It will ask you which file you wish to save it in, and, if the 
file exists, confirm that you wish to overwrite it 

restore game: Read in a previously saved game from a file. It leaves the file intact. 

Roll the dice and move forward to your new location. If you simply hit the <RETURN> key 
instead of a command, it is the same as typing roll. 


FILES 

/usr/games/lib/cards.pck Chance and Community Chest cards 

BUGS 

No command can be given an argument instead of a response to a query. 
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NAME 

number - convert Arabic numerals to English 

SYNOPSIS 

/usr/games/number 

DESCRIPTION 

Number copies the standard input to the standard output, changing each decimal number to a fully spelled 
out version. 


448 


Last change: 1 February 1983 


Sun Release 3.0 



QUIZ (6) 


GAMES AND DEMOS 


QUIZ ( 6 ) 


NAME 

quiz - test your knowledge 
SYNOPSIS 

/usr/games/quiz [ -i file ] [ -t ] [ category 1 category2 ] 

DESCRIPTION 

Quiz gives associative knowledge tests on various subjects. It asks items chosen from cate gory 1 and 
expects answers from category2 . If no categories are specified, quiz gives instructions and lists the avail- 
able categories. 

Quiz tells a correct answer whenever you type a bare newline. At the end of input, upon interrupt, or when 
questions run out, quiz reports a score and terminates. 

The -t flag specifies ‘tutorial’ mode, where missed questions are repeated later, and material is gradually 
introduced as you learn. 

The -i flag causes the named file to be substituted for the default index file. The lines of these files have 
the syntax: 

line = category newline | category line 
category = alternate | category ‘|’ alternate 
alternate = empty | alternate primary 
primary = character | *[’ category “]’ | option 
option = ‘{’ category *}’ 

The first category on each line of an index file names an information file. The remaining categories specify 
the order and contents of the data in each line of the information file. Information files have the same syn- 
tax. Backslash ‘V is used as with sA(l) to quote syntactically significant characters or to insert transparent 
newlines into a line. When either a question or its answer is empty, quiz will refrain from asking it. 

FILES 

/usr/games/quiz.k/* 

BUGS 

The construct ‘a| ab’ doesn’t work in an information file. Use ‘a{b}\ 
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NAME 

rain - animated raindrops display 

SYNOPSIS 

/usr/games/rain 

DESCRIPTION 

Rain’s display is modeled after the VAX/VMS program of the same name. The terminal has to be set for 
9600 baud to obtain the proper effect. 

As with all programs that use termcap, the TERM environment variable must be set (and exported) to the 
type of the terminal being used. 

FILES 

/etc/termcap 
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NAME 

rotcvph - rotate convex polyhedron 
SYNOPSIS 

/usr/demo/rotcvph file 
DESCRIPTION 

Rotcvph rotates a convex polyhedron with hidden surfaces removed. Using the SunCore Graphics Pack- 
age, a 3-D projection is drawn on the Sun Monochrome Bitmap Display. The mandatory file argument 
contains a polygonal object definition as described below. 

Initially the program displays a fixed view of the object The following commands may be typed at any 
time: 

n Display successive views with no waiting, 

w Wait for <SPACE> to be typed before displaying each view, 
q Exit the program. 

The format of the polygonal object definition is illustrated by this example of the definition of a pyramid: 

5 5 

- 1.0 1 . 0 - 1.0 1 . 0 - 1.0 1.0 
1.0 1 . 0 - 1.0 
1 . 0 - 1 . 0 - 1.0 
- 1 . 0 - 1 . 0 - 1.0 
- 1.0 1 . 0 - 1.0 
0.0 0.0 1.0 
4 4321 

3 154 

3 25 1 

3 352 

3 45 3 

The first line gives the number of vertices followed by the number of polygons. The second line gives the 
coordinates of a bounding box for the object. Minimum and maximum coordinate values are given for 
each of three dimensions in the order minx, maxx, miny, maxy, minz, maxz. Lines 3 through v+2 (where v 
is the number of vertices) give vertex coordinates in the order x, y, z. Lines v+3 through v+p+2 (where p is 
the number of polygons) give polygon descriptions. The first number is the number of vertices for the 
polygon. Succeeding numbers on the line are indices into the vertex list. Polygons should be planar. 
Coordinates are given in floating point format and everything else is integer. Entries on a given line are 
separated by arbitrary whitespace. A maximum of 400 vertices and 400 polygons may be defined. The 
polygon definitions may contain a maximum of 1600 instances of the vertices, /usr/demo/data contains 
several object definition files, including icosa.dat, socbal.dat, and pyramid.dat. 

The above format may be used to define non-convex objects. The program will display these objects but 
hidden surface computations will not be done correctly. 

FILES 

/usr/demo/data/* .dat Sample object definition files 

BUGS 

All floating point transformations are done twice for each view, once to draw the object and once to 
undraw it. 

Lines which are common to two visible polygons in a view are drawn twice, once for each polygon. 
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NAME 

sail - multi-user wooden ships and iron men 

SYNOPSIS 

sail [ — x ] [ num ] 

DESCRIPTION 

Sail is a computer version of Avalon Hill’s game of fighting sail originally developed by S. Craig Taylor. 

NOTES 

Sail is really two programs in one. Each player keeps track of his own ship plus a DRIVER program is 
execl’d (by the first player) to keep track of the computer’s ships. 

The player is given the first available ship in a scenario and the computer takes the rest. Obviously the 
more ships in your game, the longer the DRIVER will take to move them. If additional players join the 
game, they will be given ships and the DRIVER will have less work to do. 

HISTORICAL INFO 

Old Square Rigger’s were very maneuverable ships capable of intricate sailing. Their one main disadvan- 
tage was being unable to sail very close to the wind. The design of wooden ship allowed only for the guns 
to bear to the left and right sides. A few guns of small aspect (usually 6 or 9 pounders) could point for- 
ward, but their effect would be small compared to a 68 gun broadside of 24 pounders. The guns bear 
approximately like so: 

\ 

b 

-0 

\ 

\ 

\ up to a range of ten (for round shot) 

\ 

\ 

\ 
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An interesting phenomenon occurred when a broadside could fire down the length of an enemy ship. The 
shot tended to bounce along the deck and did several times more damage. This phenomenon was called a 
rake. It happened that a stem rake (firing from the stem to the bow) occasioned more damage than a bow 
rake, so that was the most desirable. 

\ 

b 

—0 

\ 

\ 0a — Stem rake! 

\ 

\ 

\ 

\ 

\ 

Most ships were equipped with Carronades which were very large, close range cannons. The carronades 
have a range of two in this game and can considerably add to your fire-power when they come to bear. If 
the distance to the target ship is greater than 6, the guns can only fire at the rigging. A ship’s guns could 
fire a variety of ammunition. For example: 

ROUND 

Range of 10. Good for hull or rigging hits. 

DOUBLE 

Range of 1. Extra good for hull or rigging hits. Double takes two turns to load. 

CHAIN 

Range of 3. Excellent for tearing down rigging. Cannot damage hull or guns, though. 

GRAPE 

Range of 1. Devastating against enemy crews. 

When a ship has been battered into a hulk (zero hull), it has no choice but to surrender to the firing ship. 
This ceremony is called 'striking your colours/ A struck ship has a chance of exploding or sinking after a 
while. When a ship surrenders, its point value is given to the aggressor. When a ship is captured, twice the 
point value is awarded the victor. 

Normally, ships sailed into battle with gready shortened sail to avoid excessive damage to the precious rig- 
ging. However, in this game the player can increase to full sails and move much faster if he wishes. But, 
all rigging hits incurred with full sails set are doubled. The direction rose displayed on the sample screen 
gives the maximum speeds possible for a specific ship at all attitudes to the wind. The full sail speeds are 
in parenthesis. 

Repairs can be made at the slow rate of two (hull, gun, or rigging) hits restored per three turns. 

Ships of class 3 or greater drift when there is wind at the rate of one 'square' per turn. Ships of the Line 
drift one 'square' every other turn. 

INSTRUCTIONS 

Sail follows the Avalon Hill advanced rules very closely using the optional rules for ’exploding ships’, ’full 
sails’, and some others. A few unique commands have been added which seemed to be helpful on the 
reduced screen, ’i’ is such a command. 

Boarding had to go through a major revision. To prevent immediate capture of an unprepared crew (foul- 
ing is often not reported until after boarding has commenced) the boarded ship automatically fights defen- 
sively (at a small disadvantage) if no DBP’s have been prepared. 
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The Order of Play has been eliminated for the player, but the DRIVER still abides by it. 

The commands for the player were designed to be as intelligent as possible to save typing. Some of the 

nuances I developed should be explained. 

Your prompt 

The others I will illustrate with examples. 

move(3, 2): rll /* 3 movements max, of which two 
may be 45’ turns. */ 

move(3,’2): lrl /* 3 movements max of which two may 
be 45’ turns, but the ship must 
move ahead before turning (there 
is a loss of headway after 
drifting) */ 

move(0,’0): r /* You can always make one turn 

even when you can’t move straight 
ahead. */ 

If you are grappled, fouled, or out of crew, you cannot move of course. 
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COMMANDS 

’f Fire broadsides if they bear 
T Reload 

’m’ Move (see above & below) 

’i’ Ask lookout for closest ship 
T Ask lookout for closest enemy ship 
’s’ Send a message around the fleet 
’b’ Attempt to board an enemy ship 
’L’ Unload broadsides (to change ammo) 
’B’ Recall boarding parties 
’c’ Change set of sail 
’r’ Repair 

’u’ Attempt to unfoul 
’g’ Grapple/ungrapple 
,A L’ Redraw screen 
’q’ Quit 


SCENARIOS 
Ranger vs. Drake: 

Wind from the N, blowing a fresh breeze. 

(a) Ranger 19 gun Sloop (crack crew) (7 pts) 

(b) Drake 17 gun Sloop (crack crew) (6 pts) 

The Battle of Flamborough Head: 

Wind from the S, blowing a fresh breeze. 


This is John Paul Jones first famous battle. Aboard the Bonhomme Richard, he was able to overcome the 
Serapis’s greater firepower by quickly boarding her. 

(a) Bonhomme Rich 42 gun Corvette (crack crew) (11 pts) 

(b) Serapis 44 gun Frigate (crack crew) (12 pts) 

Arbuthnot and Des Touches: 

Wind from the N, blowing a gale. 


(b) America 
(b) Befford 
(b) Adamant 
(b) London 
(b) Royal Oak 
(f) Neptune 
(f) Due Bougogne 
(0 Conquerant 
(f) Provence 
(f) Romulus 


64 gun Ship of the Line (crack crew) (20 pts) 

74 gun Ship of the Line (crack crew) (26 pts) 

50 gun Ship of the Line (crack crew) (17 pts) 

98 gun 3 Decker SOL (crack crew) (28 pts) 

74 gun Ship of the Line (crack crew) (26 pts) 

74 gun Ship of the Line (average crew) (24 pts) 
80 gun 3 Decker SOL (average crew) (27 pts) 
74 gun Ship of the Line (average crew) (24 pts) 
64 gun Ship of the Line (average crew) (18 pts) 
44 gun Ship of the Line (average crew) (10 pts) 


Suffren and Hughes: 

Wind from the S, blowing a fresh breeze. 


(b) Monmouth 74 gun Ship of the Line (average crew) (24 pts) 
(b) Hero 74 gun Ship of the Line (crack crew) (26 pts) 

(b) Isis 50 gun Ship of the Line (crack crew) (17 pts) 

(b) Superb 74 gun Ship of the Line (crack crew) (27 pts) 

(b) Burford 74 gun Ship of the Line (average crew) (24 pts) 
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(f) Flamband 50 gun Ship of the Line (average crew) (14 pts) 
(f) Annibal 74 gun Ship of the Line (average crew) (24 pts) 
(f) Severe 64 gun Ship of the Line (average crew) (18 pts) 

(f) Brilliant 80 gun Ship of the Line (crack crew) (3 1 pts) 

(f) Sphinx 80 gun Ship of the Line (average crew) (27 pts) 

Nymphe vs. Cleopatre: 

Wind from the S, blowing a fresh breeze. 


(b) Nymphe 36 gun Frigate (crack crew) (1 1 pts) 

(f) Cleopatre 36 gun Frigate (average crew) (10 pts) 

Mars vs. Hercule: 

Wind from the S, blowing a fresh breeze. 

(b) Mars 74 gun Ship of the Line (crack crew) (26 pts) 

(f) Hercule 74 gun Ship of the Line (average crew) (23 pts) 


Ambuscade vs. Baionnaise: 

Wind from the N, blowing a fresh breeze. 


(b) Ambuscade 32 gun Frigate (average crew) (9 pts) 
(f) Baionnaise 24 gun Corvette (average crew) (9 pts) 

Constellation vs. Insurgent: 

Wind from the S, blowing a gale. 


(a) Constellation 38 gun Corvette (elite crew) (17 pts) 
(f) Insurgent 36 gun Corvette (average crew) (11 pts) 


Constellation vs. Vengeance: 

Wind from the S, blowing a fresh breeze. 


(a) Constellation 38 gun Corvette (elite crew) (17 pts) 
(f) Vengeance 40 gun Frigate (average crew) (15 pts) 


The Battle of Lissa: 

Wind from the S, blowing a fresh breeze. 


(b) Amphion 
(b) Active 
(b) Volage 
(b) Cerberus 
(f) Favorite 
(f) Flore 
(f) Danae 
(f) Bellona 
(f) Corona 
(0 Carolina 


32 gun Frigate (elite crew) (13 pts) 
38 gun Frigate (elite crew) (18 pts) 

22 gun Frigate (elite crew) (11 pts) 

32 gun Frigate (elite crew) (13 pts) 
40 gun Frigate (average crew) (15 pts) 
40 gun Frigate (average crew) (15 pts) 
40 gun Frigate (crack crew) (17 pts) 
32 gun Frigate (green crew) (9 pts) 

40 gun Frigate (green crew) (12 pts) 
32 gun Frigate (green crew) (7 pts) 


Constitution vs. Guerriere: 

Wind from the SW, blowing a gale. 


(a) Constitution 44 gun Corvette (elite crew) (24 pts) 

(b) Guerriere 38 gun Frigate (crack crew) (15 pts) 

United States vs. Macedonian: 

Wind from the S, blowing a fresh breeze. 
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(a) United States 44 gun Frigate (elite crew) (24 pts) 

(b) Macedonian 38 gun Frigate (crack crew) ( 1 6 pts) 

Constitution vs. Java: 

Wind from the S, blowing a fresh breeze. 

(a) Constitution 44 gun Corvette (elite crew) (24 pts) 

(b) Java 38 gun Corvette (crack crew) (19 pts) 

Chesapeake vs. Shannon: 

Wind from the S, blowing a fresh breeze. 

(a) Chesapeake 38 gun Frigate (average crew) (14 pts) 

(b) Shannon 38 gun Frigate (elite crew) (17 pts) 

The Battle of Lake Erie: 

Wind from the S, blowing a light breeze. 

(a) Lawrence 20 gun Sloop (crack crew) (9 pts) 

(a) Niagara 20 gun Sloop (elite crew) (12 pts) 

(b) Lady Prevost 13 gun Brig (crack crew) (5 pts) 

(b) Detroit 19 gun Sloop (crack crew) (7 pts) 

(b) Q. Charlotte 17 gun Sloop (crack crew) (6 pts) 

Wasp vs. Reindeer: 

Wind from the S, blowing a light breeze. 


(a) Wasp 20 gun Sloop (elite crew) (12 pts) 

(b) Reindeer 18 gun Sloop (elite crew) (9 pts) 

Constitution vs. Cyane and Levant: 

Wind from the S, blowing a moderate breeze. 

(a) Constitution 44 gun Corvette (elite crew) (24 pts) 

(b) Cyane 24 gun Sloop (crack crew) (11 pts) 

(b) Levant 20 gun Sloop (crack crew) (10 pts) 

Pellew vs. Droits de L’Homme: 

Wind from the N, blowing a gale. 


(b) Indefatigable 44 gun Frigate (elite crew) (14 pts) 

(b) Amazon 36 gun Frigate (crack crew) (14 pts) 

(f) Droits L’Hom 74 gun Ship of the Line (average crew) (24 pts) 

Aigeciras: 

Wind from the SW, blowing a moderate breeze. 


(b) Caesar 
(b) Pompee 
(b) Spencer 
(b) Hannibal 
(s) Real-Carlos 
(s) San Fernando 
(s) Argonauta 
(s) San Augustine 
(f) Indomptable 


80 gun Ship of the Line (crack crew) (31 pts) 

74 gun Ship of the Line (crack crew) (27 pts) 

74 gun Ship of the Line (crack crew) (26 pts) 

98 gun 3 Decker SOL (crack crew) (28 pts) 

112 gun 3 Decker SOL (green crew) (27 pts) 

96 gun 3 Decker SOL (green crew) (24 pts) 

80 gun Ship of the Line (green crew) (23 pts) 

74 gun Ship of the Line (green crew) (20 pts) 
80 gun Ship of the Line (average crew) (27 pts) 


(f) Desaix 74 gun Ship of the Line (average crew) (24 pts) 
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Lake Champlain: 

Wind from the N, blowing a fresh breeze. 


(a) Saratoga 
(a) Eagle 
(a) Ticonderoga 

(a) Preble 

(b) Confiance 
(b) Linnet 
(b) Chubb 


26 gun Sloop (crack crew) (12 pts) 
20 gun Sloop (crack crew) (11 pts) 

17 gun Sloop (crack crew) (9 pts) 

7 gun Brig (crack crew) (4 pts) 

37 gun Frigate (crack crew) (14 pts) 
16 gun Sloop (elite crew) (10 pts) 

1 1 gun Brig (crack crew) (5 pts) 


Last Voyage of the USS President: 

Wind from the N, blowing a fresh breeze. 


(a) President 

(b) Endymion 
(b) Pomone 
(b) Tenedos 


44 gun Frigate (elite crew) (24 pts) 

40 gun Frigate (crack crew) (17 pts) 
44 gun Frigate (crack crew) (20 pts) 
38 gun Frigate (crack crew) (15 pts) 


Hornblower and the Natividad: 

Wind from the E, blowing a gale. 


A scenario for you Homy fans. Remember, he sank the Natividad against heavy odds and winds. Hint: 
don’t try to board the Natividad, her crew is much bigger, albeit green. 


(b) Lydia 36 gun Frigate (elite crew) (13 pts) 

(s) Natividad 50 gun Ship of the Line (green crew) (14 pts) 

Curse of the Flying Dutchman: 

Wind from the S, blowing a fresh breeze. 


Just for fun, take the Piece of cake. 


(s) Piece of Cake 24 gun Corvette (average crew) (9 pts) 

(f) Flying Dutchy 120 gun 3 Decker SOL (elite crew) (43 pts) 


The South Pacific: 

Wind from the S, blowing a strong breeze. 


(a) USS Scurvy 

(b) HMS Tahiti 
(s) Australian 
(f) Bikini Atoll 


136 gun 3 Decker SOL (mutinous crew) (27 pts) 
120 gun 3 Decker SOL (elite crew) (43 pts) 

32 gun Frigate (average crew) (9 pts) 

7 gun Brig (crack crew) (4 pts) 


Hornblower and the battle of Rosas 

Wind from the E, blowing a fresh breeze. 


The only battle Hornblower ever lost. He was able to dismast one 
ship and stem rake another’s though. See if you can do as well. 


(b) Sutherland 
(f) Turenne 
(f) Nightmare 
(f) Paris 
(f) Napolean 


74 gun Ship of the Line (crack crew) (26 pts) 

80 gun 3 Decker SOL (average crew) (27 pts) 

74 gun Ship of the Line (average crew) (24 pts) 
1 12 gun 3 Decker SOL (green crew) (27 pts) 

74 gun Ship of the Line (green crew) (20 pts) 
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Cape Horn: 

Wind from the NE, blowing a strong breeze. 

(a) Concord 80 gun Ship of the Line (average crew) (27 pts) 

(a) Berkeley 98 gun 3 Decker SOL (crack crew) (28 pts) 

(b) Thames 120 gun 3 Decker SOL (elite crew) (43 pts) 

(s) Madrid 112 gun 3 Decker SOL (green crew) (27 pts) 

(f) Musket 80 gun 3 Decker SOL (average crew) (27 pts) 

New Orleans: 

Wind from the SE, blowing a fresh breeze. 

Watch that little Cypress go! 

(a) Alligator 120 gun 3 Decker SOL (elite crew) (43 pts) 

(b) Firefly 74 gun Ship of the Line (crack crew) (27 pts) 

(b) Cypress 44 gun Frigate (elite crew) (14 pts) 

Botany Bay: 

Wind from the N, blowing a fresh breeze. 

(b) Shark 64 gun Ship of the Line (average crew) (18 pts) 

(f) Coral Snake 44 gun Corvette (elite crew) (24 pts) 

(f) Sea Lion 44 gun Frigate (elite crew) (24 pts) 

Voyage to the Bottom of the 

Wind from the NW, blowing a fresh breeze. 

This one is dedicated to David Hedison. 

(a) Seaview 120 gun 3 Decker SOL (elite crew) (43 pts) 

(a) Flying Sub 40 gun Frigate (crack crew) (17 pts) 

(b) Mermaid 136 gun 3 Decker SOL (mutinous crew) (27 pts) 

(s) Giant Squid 112 gun 3 Decker SOL (green crew) (27 pts) 

Frigate Action: 

Wind from the E, blowing a fresh breeze. 

(a) Killdeer 40 gun Frigate (average crew) (15 pts) 

(b) Sandpiper 40 gun Frigate (average crew) (15 pts) 

(s) Curlew 38 gun Frigate (crack crew) (16 pts) 

The Battle of Midway: 

Wind from the E, blowing a moderate breeze. 

(a) Enterprise 80 gun Ship of the Line (crack crew) (31 pts) 

(a) Yorktown 80 gun Ship of the Line (average crew) (27 pts) 
(a) Hornet 74 gun Ship of the Line (average crew) (24 pts) 

(f) Akagi 1 12 gun 3 Decker SOL (green crew) (27 pts) 

(f) Kaga 96 gun 3 Decker SOL (green crew) (24 pts) 

(f) Soryu 80 gun Ship of the Line (green crew) (23 pts) 

EXAMPLE OF MOVE: 

/ Max distance (including turns) 

/ Max number of 45 degree turns (one at a time only) 

/ / 

Move(3, 2): rll /* move right, ahead, left 
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* 

* 0 START 

* b 

* ... 

* 

* bO RIGHT 

* 

* 

* bO ONE 

* 

* 0 

* b LEFT 

* 

SAMPLE GAME: 

tutorial% sail 
Choose a scenario: 


NUMBER SHIPS IN PLAY TITLE 

0) : 2 no Ranger vs. Drake 

1) : 2 no The Battle of Flamborough Head 

2) : 10 no Arbuthnot and Des Touches 

3) : 10 no Suffren and Hughes 

4) : 2 no Nymphe vs. Cleopatre 

5) : 2 no Mars vs. Hercule 

6) : 2 no Ambuscade vs. Baionnaise 

7) : 2 no Constellation vs. Insurgent 

8) : 2 no Constellation vs. Vengeance 

9) : 10 no The Battle of Lissa 

10) : 2 no Constitution vs. Guerriere 

11) : 2 no United States vs. Macedonian 

12) : 2 no Constitution vs. Java 

13) : 2 no Chesapeake vs. Shannon 

14) : 5 no The Battle of Lake Erie 

15) : 2 no Wasp vs. Reindeer 

16) : 3 no Constitution vs. Cyane and Levant 

17) : 3 no Pellew vs. Droits de L’Homme 

18) : 10 no Algeciras 

19) : 7 no Lake Champlain 

20) : 4 no Last Voyage of the USS President 

21) : 2 no Homblower and the Natividad 

22) : 2 no Curse of the Flying Dutchman 

23) : 4 no The South Pacific 

24) : 5 no Homblower and the battle of Rosas bay 

25) : 5 no Cape Horn 

26) : 3 no New Orleans 

27) : 3 no Botany Bay 

28) : 4 no Voyage to the Bottom of the Sea 

29) : 3 no Frigate Action 

30) : 6 no The Battle of Midway 

Scenario number? 21 
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SAIL(6) 


GAMES AND DEMOS 


SAIL ( 6 ) 


Your ship is the Lydia, a 36 gun Frigate (elite crew). 

Your name, Captain? Dave #1 

Initial broadside left (grape, chain, round, double): d 

Initial broadside right (grape, chain, round, double): r 

Class 3 (36 guns) Frigate ’Lydia’ (bO) Points: 0 Fouls: 0 Grapples: 0 


0 

b 


'0 — a sinking ship 
#1 - an exploding ship 


bow of Lydia 


1 


! — a struck ship SO 


I wind speed -5+ | 

| and direction 
I (blowing from right) 


stem of Natividad 
Natividad has full sails set 


Turn 0 

Aye aye, Sir load: port and starboard - Load D! R! 0 1(1) 

Hull 9 \|/ 

crew: 3 sections Crew 4 42 i(i) 

guns: port and starboard -- Guns 4 4 /|\ 

carronades: port and starboard - Carr 2 2 | 3 ( 5 ) 

rigging 4 masts Rigg 5 5 5 5 2(4) 
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SNAKE (6) 


GAMES AND DEMOS 


SNAKE (6) 


NAME 

snake, snscore - display chase game 
SYNOPSIS 

/usr/games/snake [ -w n ] [ -1 n ] 

/usr/games/snscore 

DESCRIPTION 

Snake is a display-based game which must be played on a CRT terminal from among those supported by 
vi(l). The object of the game is to make as much money as possible without getting eaten by die snake. 
The -1 and -w options allow you to specify the length and width of the field. By default the entire screen 
(except for the last column) is used. 

You are represented on the screen by an I. The snake is 6 squares long and is represented by S’s. The 
money is $, and an exit is #. Your score is posted in the upper left hand comer. 

You can move around using the same conventions as vi(l), the h, j, k, and 1 keys work, as do the arrow 
keys. Other possibilities include: 

sefc These keys are like hjkl but form a directed pad around the d key. 

HJKL These keys move you all the way in the indicated direction to the same row or column as the 
money. This does not let you jump away from the snake, but rather saves you from having to type 
a key repeatedly. The snake still gets all his turns. 

SEFC Likewise for the upper case versions on the left. 

ATPB These keys move you to the four edges of the screen. Their position on the keyboard is the 
mnemonic, e.g. P is at the far right of the keyboard. 

x This lets you quit the game at any time, 
p Points in a direction you might want to go. 
w Space warp to get out of tight squeezes, at a price. 

! Shell escape 

A Z Suspend the snake game, on systems which support it. Otherwise an interactive shell is started up. 

To earn money, move to the same square the money is on. A new $ will appear when you earn the current 
one. As you get richer, the snake gets hungrier. To leave the game, move to the exit (#). 

A record is kept of the personal best score of each player. Scores are only counted if you leave at the exit, 
getting eaten by the snake is worth nothing. 

As in pinball, matching the last digit of your score to the number which appears after the game is worth a 
bonus. 

To see who wastes time playing snake, run I usrl games! snscore . 

FILES 

/usr/games/lib/snakerawscores database of personal bests 
/usr/games/lib/snake.log log of games played 

BUGS 

When playing on a small screen, it’s hard to tell when you hit the edge of the screen. 

The scoring function takes into account the size of the screen. A perfect function to do this equitably has 
not been devised. 
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SUNCOREDEMOS ( 6 ) 


GAMES AND DEMOS 


SUNCOREDEMOS (6) 


NAME 

suncoredemos - demonstrate SunCore Graphics Package 
SYNOPSIS 

/usr/demo/cproduct 
/ usr/demo/cshademo 
/usr/demo/cvlsi 

DESCRIPTION 

Suncoredemos is a collection of simple programs demonstrating the SunCore Graphics Package. Each pro- 
gram is briefly described below. These programs generate all graphics output using subroutine calls to 
SunCore. To exit each program, generate an interrupt signal by typing the appropriate key (usually 
<DELETE>). 

cproduct color Sun architecture demo 

Requires Sun Color Graphics Display, 
cshademo shaded surface polygons demo 

Requires Sun Color Graphics Display, 
cvlsi color vlsi layout demo 

Requires Sun Color Graphics Display. 
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TREK( 6) 


GAMES AND DEMOS 


TREK(6) 


NAME 

trek - trekkie game 
SYNOPSIS 

/usr/games/trek [ [ -a ] file ] 

DESCRIPTION 

Trek is a game of space glory and war. Below is a summary of commands. For complete documentation, 
see Trek by Eric Allman. 

If a filename is given, a log of the game is written onto that file. If the -a flag is given before the filename, 
that file is appended to, not truncated. 

The game will ask you what length game you would like. Valid responses are “short”, “medium”, and 
“long”. You may also type “restart”, which restarts a previously saved game. You will then be 
prompted for the skill, to which you must respond “novice”, “fair”, “good”, “expert”, “commadore”, 
or “impossible”. You should normally start out with a novice and work up. 

In general, throughout the game, if you forget what is appropriate the game will tell you what it expects if 
you just type in a question mark. 


COMMAND SUMMARY 
abandon 
cloak up/down 
computer request; ... 
destruct 
help 
Irscan 

phasers automatic amount 

phasers manual amtl coursel spreadl ... 

torpedo course [yes] angle/no 

ram course distance 

shell 

srscan [yes/no] 

status 

undock 

warp warpfactor 


capture 

damages 

dock 

impulse course distance 
move course distance 


rest time 
shields up/down 

terminate yes/no 
visual course 
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GAMES AND DEMOS 


VWCVPH (6) 


NAME 

vwcvph - view convex polyhedron 
SYNOPSIS 

/usr/demo/vwcvph file 
DESCRIPTION 

Vwcvph allows the user to view a convex polyhedron from various positions with hidden surfaces removed. 
The viewing position is selected using the mouse. Using the SunCore Graphics Package, a 3-D projection 
is drawn on the Sun Monochrome Bitmap Display. The mandatory file argument contains a polygonal 
object definition as described in the manual page for /usr/demo/rotcvph. 

The program operates in two modes: DisplayObject mode and SelectView mode. The program starts in 
DisplayObject mode. 

DisplayObject: The object is displayed in 3-D perspective with hidden surfaces removed. Type "q" while 
in this mode to exit the program. Hit mouse button 3 to switch to SelectView mode. 

SelectView: Schematic projections of the outline of the object are shown and the mouse is used to select a 
viewing position. Use button 1 to set x and button 2 to set y in the Front View. Use button 2 to set z in the 
Top View. Hit button 3 to switch to DisplayObject mode. 

The view shown in DisplayObject mode is drawn using the conventions that the viewer is always looking 
from the viewing position toward the center of the object and that the positive y axis on the screen is the 
projection of the positive y axis in object coordinates. 

The input file may define non-convex objects. The program will display these objects but hidden surface 
computations will not be done correctly. 

FILES 

/ usr/demo/ data/* .dat Sample object definition files 

BUGS 

Lines which are common to two visible polygons in a view are drawn twice, once for each polygon. 


Sun Release 3.0 


Last change: 22nd February 1983 


465 



WORM ( 6 ) 


GAMES AND DEMOS 


WORM (6) 


NAME 

worm - Play the growing worm game 
SYNOPSIS 

/usr/games/worm [ size ] 

DESCRIPTION 

In worm, you are a little worm, your body is the "o"’s on the screen and your head is the You move 
with the hjkl keys (as in the game snake). If you don’t press any keys, you continue in the direction you 
last moved. The upper case HJKL keys move you as if you had pressed several (9 for HL and 5 for JK) of 
the corresponding lower case key (unless you run into a digit, then it stops). 

On the screen you will see a digit, if your worm eats the digit is will grow longer, the actual amount longer 
depends on which digit it was that you ate. The object of the game is to see how long you can make the 
worm grow. 

The game ends when the worm runs into either the sides of the screen, or itself. The current score (how 
much the worm has grown) is kept in the upper left comer of the screen. 

The optional argument, if present, is the initial length of the worm. 

BUGS 

If the initial length of the worm is set to less than one or more than 75, various strange things happen. 
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GAMES AND DEMOS 


WORMS (6) 


NAME 

worms - animate worms on a display terminal 
SYNOPSIS 

/usr/games/worms [ -field ] [ -length # ] [ -number # ] [ -trail ] 

DESCRIPTION 

Brian Horn (citheplbdh) showed me a TOPS-20 program on the DEC-2136 machine called WORM, and 
suggested that I write a similar program that would run under Unix. I did, and no apologies. 

-field makes a "field" for the worm(s) to eat; -trail causes each worm to leave a trail behind it You can 
figure out the rest by yourself. 

FILES 

/etc/termcap 

SEE ALSO 

Snails, by Karl Heuer 

BUGS 

The lower-right-hand character position will not be updated properly on a terminal that wraps at the right 
margin. 

Terminal initialization is not performed. 
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WUMP(6) 


GAMES AND DEMOS 


WUMP(6) 


NAME 

wump - the game of hunt-the-wumpus 

SYNOPSIS 

/usr/games/wump 

DESCRIPTION 

Wump plays the game of ‘Hunt the Wumpus.’ A Wumpus is a creature that lives in a cave with several 
rooms connected by tunnels. You wander among the rooms, trying to shoot the Wumpus with an arrow, 
meanwhile avoiding being eaten by the Wumpus and falling into Bottomless Pits. There are also Super 
Bats which are likely to pick you up and drop you in some random room. 

The program asks various questions which you answer one per line; it will give a more detailed description 
if you want. 

This program is based on one described in People's Computer Company, 2, 2 (November 1973). 
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TABLES 


INTRO (7) 


NAME 

miscellaneous - miscellaneous useful information pages 
DESCRIPTION 

This section contains miscellaneous documentation, mostly in the area of text processing macro packages 
for troff(l). 


ascii 

eqnchar 

hier 

mailaddr 

man 

me 

ms 


map of ASCII character set 
special character definitions for eqn 
file system hierarchy 
mail addressing description 
macros to typeset manual pages 
macros for formatting papers 
macros for formatting manuscripts 
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ASCII (7) 


TABLES 


ASCII (7) 


NAME 

ascii - map of ASCII character set 

SYNOPSIS 

cat /usr/pub/ascii 

DESCRIPTION 

Ascii is a map of the ASCII character set, to be printed as needed. It contains: 


|000 

nul 

|001 

soh 

1002 

s tx 

1003 

etx 

|004 

eot 

|005 

enq 

|006 

ack|007 

be 1 1 

|010 

bs 

|011 

ht 

1012 

nl 

|013 

vt 

|014 

np 

|015 

cr 

|016 

so 

|017 

si | 

|020 

die 

|021 

dc 1 

|022 

dc2 

1023 

dc3 

|024 

dc4 

|025 

nak|026 

syn 

|027 

e tb | 

|030 

can 

|031 

em 

|032 

sub 

|033 

esc 

|034 

fs 

|035 

gs 

|036 

rs 

|037 

us | 

|040 

sp 

|041 

i 

|042 

tt 

|043 

# 

|044 

$ 

|045 

% 

|046 

& 

|047 

' 1 

|050 

( 

1051 

) 

|052 

* 

|053 

+ 

|054 

y 

|055 

- 

|056 

. 

|057 

/ | 

1060 

0 

|061 

1 

|062 

2 

1063 

3 

1064 

4 

|065 

5 

|066 

6 

|067 

7 I 

1070 

8 

|071 

9 

|072 

; 

1073 

> 

|074 

< 

|075 

= 

|076 

> 

|077 

7 | 

|100 

@ 

|101 

A 

|102 

B 

|103 

C 

|104 

D 

|105 

E 

|106 

F 

|107 

G | 

|110 

H 

mi 

I 

|112 

J 

1113 

K 

|114 

L 

|115 

M 

|116 

N 

|117 

0 | 

1 120 

P 

|121 

Q 

|122 

R 

|123 

S 

|124 

T 

1 125 

U 

|126 

V 

|127 

W 1 

|130 

X 

|131 

Y 

1 132 

Z 

1 133 

[ 

1134 

\ 

|135 

] 

1 136 

A 

|137 


1 140 


|141 

a 

|142 

b 

|143 

c 

|144 

d 

1 145 

e 

1146 

f 

|147 

g 1 

|150 

h 

|151 

i 

1 152 

j 

|153 

k 

|154 

1 

1155 

m 

|156 

n 

|157 

o I 

1 160 

P 

|161 

q 

|162 

r 

1 163 

s 

|164 

t 

|165 

u 

|166 

V 

1167 

w | 

|170 

X 

1171 

y 

|172 

z 

1173 

{ 

|174 

1 

|175 

} 

|176 


1177 

del| 

| 00 

nul 

1 01 

soh 

| 02 

stx 

| 03 

etx 

| 04 

eot 

| 05 

enq 

| 06 

ack 

| 07 

bel| 

| 08 

bs 

| 09 

ht 

| 0a 

nl 

| 0b 

vt 

| 0c 

np 

| Od 

cr 

| Oe 

so 

| Of 

si | 

1 io 

die 

1 11 

dc 1 

1 12 

dc2 

1 13 

dc3 

1 14 

dc4 

1 15 

nak 

1 16 

syn 

1 17 

e tb | 

1 18 

can 

1 19 

em 

1 la 

sub 

1 lb 

esc 

1 lc 

fs 

1 Id 

gs 

1 le 

rs 

1 If 

us | 

| 20 

sp 

1 21 

j 

| 22 

tt 

| 23 

# 

1 24 

$ 

1 25 

% 

| 26 

& 

| 27 

/ 1 

1 28 

( 

| 29 

) 

| 2a 

* 

| 2b 

+ 

| 2c 

y 

1 2d 

— 

| 2e 

, 

1 2f 

/ | 

| 30 

0 

1 31 

1 

| 32 

2 

| 33 

3 

1 34 

4 

1 35 

5 

| 36 

6 

1 37 

7 I 

| 38 

8 

| 39 

9 

1 3a 

: 

| 3b 

1 

1 3c 

< 

1 3d 

= 

1 3e 

> 

1 3f 

7 | 

| 40 

@ 

1 41 

A 

1 42 

B 

1 43 

C 

| 44 

D 

1 45 

E 

| 46 

F 

1 47 

G | 

| 48 

H 

| 49 

I 

| 4a 

J 

| 4b 

K 

| 4c 

L 

| 4d 

M 

| 4e 

N 

1 4f 

0 | 

1 50 

P 

1 51 

Q 

1 52 

R 

| 53 

S 

1 54 

T 

| 55 

U 

| 56 

V 

1 57 

W 1 

| 58 

X 

1 59 

Y 

1 5a 

Z 

| 5b 

[ 

1 5c 

\ 

1 5d 

] 

1 5e 

A 

1 5f 


| 60 


1 61 

a 

| 62 

b 

| 63 

c 

| 64 

d 

| 65 

e 

| 66 

f 

1 67 

g 1 

| 68 

h 

| 69 

i 

| 6a 

j 

| 6b 

k 

| 6c 

1 

| 6d 

m 

| 6e 

n 

1 6f 

o I 

| 70 

P 

1 71 

q 

| 72 

r 

1 73 

s 

1 74 

t 

1 75 

u 

1 76 

V 

| 77 

w | 

| 78 

X 

| 79 

y 

1 7a 

z 

1 7b 

{ 

1 7c 

1 

1 7d 

} 

1 7e 

~ 

1 7f 

del| 


FILES 

/usr/pub/ascii 
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EQNCHAR ( 7 ) 


TABLES 


EQNCHAR (7) 


NAME 

eqnchar - special character definitions for eqn 
SYNOPSIS 

eqn /usr/pub/eqnchar [ files ] | troff [ options ] 
neqn /usr/pub/eqnchar [ files ] | nroff [ options ] 

DESCRIPTION 

Eqnchar contains troff and nroff character definitions for constructing characters that are not available on 
the Graphic Systems typesetter. These definitions are primarily intended for use with eqn and neqn. It 
contains definitions for the following characters 


ciplus 

© 

// 

// 

square 

□ 

citimes 

0 

langle 

/ 

\ 

circle 

O 

wig 

~ 

rangle 

\ 

/ 

blot 

□ 

-wig 

= 

hbar 

n 

bullet 

e 

>wig 

> 

ppd 


prop 

oc 

<wig 

< 

<-> 


empty 

0 

=wig 

= 

<=> 


member 

€ 

star 

* 

/< 

* 

nomem 

4 

bigstar 

* 

/> 

4> 

cup 

u 

=dot 

= 

ang 

!_ 

cap 

n 

orsign 

V 

rang 

fr 

incl 

E 

andsign 

A 

3dot 


subset 

a 

=del 

A 

tv 


supset 

3 

oppA 

■V 

quarter 

>/4 

! subset 

c 

oppE 

angstrom 

3 

A 

3quarter 3 A 
degree ° 

Isupset 

2 


FILES 

/usr/pub/eqnchar 

SEE ALSO 

troff(l), eqn(l) 
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HffiR(7) 


TABLES 


HER (7) 


NAME 

hier - file system hierarchy 
DESCRIPTION 

The following outline gives a quick tour through a typical directory hierarchy. 


/bin 


root directory 

utilitiy programs 

/dev 

/bin/ar 
/bin/as 
/bin/awk 
/bin/ cat 
/bin/cc 

/bin/who 

devices and special files 


/dev/console 

console terminal 


/dev/drum 

memory paging device 


/ dev/ *mem memory special files 
/ dev/null 

system wastebasket 


/dev/pty [p-z] * 

pseudo-terminal driver(s) 


/ dev/ tty* terminals 
/dev/ tty [p-z] * 

pseudo-terminals 

/etc 

/dev/ vme* VME bus special files 

/ dev/ win* window system special files 

system administration files & progra , 


/etc/cron 
/ etc/f astboot 
/ etc/ f asthalt 

/etc/fsck 

/etc/fstab 

table of mountable filesystems 


/etc /group 

system group membership table 


/etc/hosts 

list of systems on the network 


/etc/hosts .equiv 

list of trusted systems 


/etc/motd 

message-of-the-day file 


/etc /mount 
/etc/mtab 

table of mounted filesystems 


/etc/passwd 

password file 


/etc/print cap 

table of printers and capabilities 


/etc/termcap 

table of terminal devices and capabu 


/etc/ttys 

terminal initialization info 
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TABLES 


HER (7) 
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/etc/ttytype 

/etc/utmp 

/etc/yp 

/lost+found 

/private 

/private/usr2 

/ stand 
/usr 

/usr /name 


table of connected terminals 

table of users logged in 
system yellow-pages directory 

detached filesystems for f sck 

client workstation files 
directory for guest accounts 

standalone programs ( not run under 

general-purpose directory 

home directory for name 


/ usr I name I . cshrc 
/usr/ name/ . login 
/usr / name/ . logout 
/usr I name I . exrc 
/ usr /name I .mailrc 

/usr/ name /filename 

/ usr/ name / directory 

/usr/ name /directory /filename 


/usr directory mounted from anotl 
system administration files 
/usr/adm/lastlog table of most recent logins 

more utility programs 

/usr/bin/addbib 
/usr/bin/adjacent screens 
/usr/bin/ align_eguals 
/usr/bin/at 
/usr/bin/basename 
/usr/bin/bc 
/usr/bin/cal 

/usr/bin/ ypwhich 

/usr/crash 

/usr/dict 

/usr/dict/words 
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system crash files & programs 
dictionary files 
dictionary wordlist 
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/usr /host 
/usr/adm 

/usr/bin 



HER (7) 


TABLES 


HIER ( 7 ) 


/usr/etc 

/usr/etc/ac 

/usr/etc/catman 

/usr/etc/yp 

/usr/games 

/ usr/ include 

/usr/include/ f 77 

/usr/include/images 

/usr/include/nfs 

/usr/include/pascal 
/usr/ include /pixrect 

/usr/include/sys 


/usr/lib 

/usr/lib/ . rootmenu 
/usr/lib/ . suntools 

/usr/lib/ . textswrc 

/usr/lib/Cshrc 

/usr/lib/Exrc 

/us r / lib/ Login 

/usr/lib/Logout 

/usr/lib/Mailrc 

/usr/lib/atrun 

/usr/lib/calendar 

/usr/lib/crontab 

/usr/lib/de£aults 

/usr/ lib/font 

/ usr/ lib/tmac 


/usr/local 

/usr/local/lib 

/usr/man 

/usr/man/cat [1-8] 
/usr/man/man [1-8] 


more system administration files and 

yellow pages directory 

games and demos 

standard C tinclude files 

Fortran include files 

icon images 

NFS include files 

Pascal include files 
pixrect include files 

system internals include files 

library routines and other useful stufi 
sample setup files for suntools 

sample setup files for for csh, mail 


directory for window-system defaults 
troff fonts 

troff macro-package files 

local utility programs 
local libraries 

Manual Page Sources 
formatted pages 
source files 
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TABLES 


HIER ( 7 ) 


/usr/preserve 

/usr/sccs 

/usr/spool 

/usr/spool/mail 
/use/ spool/lpd 


/usr/tmp 

/usr/ucb 

/usr/ ucb/Mail 
/usr/ucb/biff 
/usr/ucb/ ccat 
/usr/ucb/ checknr 
/usr/ucb/ chsh 


SEE ALSO 

ls(l), whatis(l), whereis(l), which (1), ncheck(8), find(l), grep(l) 

BUGS 

The position of files is subject to change without notice. 


preserves editor files from crashes 

sees programs 

delayed execution files 
system mailboxes 
printer queue(s) 

temporary files 

programs developed at U.C. Berkele 
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TABLES 


MAILADDR ( 7 ) 


NAME 

mailaddr - mail addressing description 
DESCRIPTION 

Mail addresses are based on the ARPANET protocols listed at the end of this manual page. These 
addresses are in the general format 

user@domain 

where a domain is a hierarchical dot separated list of subdomains. For example, the address 
eric@monet.Berkeley.ARPA 

is normally interpreted from right to left: the message should go to the ARP A name tables (which do not 
correspond exactly to the physical ARPANET), then to the Berkeley gateway, after which it should go to 
the local host monet. When the message reaches monet it is delivered to the user “eric”. 

Unlike some other forms of addressing, this does not imply any routing. Thus, although this address is 
specified as an ARPA address, it might travel by an alternate route if that was more convenient or efficient 
For example, at Berkeley the associated message would probably go directly to monet over the Ethernet 
rather than going via the Berkeley ARPANET gateway. 

Abbreviation. Under certain circumstances it may not be necessary to type the entire domain name. In gen- 
eral anything following the first dot may be omitted if it is the same as the domain from which you are 
sending the message. For example, a user on “calder.Berkeley.ARPA” could send to “eric@monet” 
without adding the ‘ ‘ .Berkeley .ARPA’ ’ since it is the same on both sending and receiving hosts. 

Certain other abbreviations may be permitted as special cases. For example, 
can be referenced without adding the “.ARPA” as long as their names do 
name. 

Compatibility. Certain old address formats are converted to the new format 
the previous mail system. In particular, 

host:user 

is converted to 

user@host 

to be consistent with the rep (1C) command. 

Also, the syntax: 

hostluser 

is converted to: 

user@host.UUCP 

This is normally converted back to the “hostluser” form before being sent on for compatibility with older 
UUCP hosts. 

The current implementation is not able to route messages automatically through the UUCP network. This 
feature is planned for the 4.2 release. Until that time you must explicitly tell the mail system which hosts to 
send your message through to get to your final destination. 

Case Distinctions. Domain names (i.e., anything after the “@” sign) may be given in any mixture of upper 
and lower case with the exception of UUCP hostnames. Most hosts accept any mixture of case in user 
names, with the notable exception of MULTICS sites. 

Differences with ARPA Protocols. Although the UNIX addressing scheme is based on the ARPA mail 
addressing protocols, there are some significant differences. 

At the time of this writing the only “top level” domain defined by ARPA is the “.ARPA” domain itself. 
This is further restricted to having only one level of host specifier. That is, the only addresses that ARPA 
accepts at this time must be in the format “user@host.ARPA” (where “host” is one word). In particular, 


at Berkeley ARPANET hosts 
not conflict with a local host 

to provide compatibility with 
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addresses such as: 

eric@monet.Berkeley.ARPA 

are not currently legal under the ARPA protocols. For this reason, these addresses are converted to a dif- 
ferent format on output to the ARPANET, typically: 

eric%monet@Berkeley.ARPA 

Route-addrs. Under some circumstances it may be necessary to route a message through several hosts to 
get it to the final destination. Normally this routing is done automatically, but sometimes it is desirable to 
route the message manually. An address that shows these relays are termed “route-addrs.” These use the 
syntax: 

<@hosta,@hostb:user@hostc> 

This specifies that the message should be sent to hosta, from there to hostb, and finally to hostc. This path 
is forced even if there is a more efficient path to hostc. 

Route-addrs occur frequently on return addresses, since these are generally augmented by the software at 
each host. It is generally possible to ignore all but the “user@host” part of the address to determine the 
actual sender. 

Postmaster. Every site is required to have a user or user alias designated “postmaster” to which problems 
with the mail system may be addressed. 

CSNET. Messages to CSNET sites can be sent to “user.host@UDel-Relay”. 

BERKELEY 

The following comments apply only to the Berkeley environment. 

Host Names. Many of the old familiar host names are being phased out In particular, single character 
names as used in Berknet are incompatible with the larger world of which Berkeley is now a member. For 
this reason the following names are being obsoleted. You should notify any correspondents of your new 


address as soon as possible. 

OLD 

NEW 

j ingvax 

ucbingres 

P 

ucbcad 

r arpavax 

ucbarpa 

v csvax 

ucbemie 

n 

ucbkim 

y 

ucbcory 




The old addresses will be rejected as unknown hosts sometime in the near future. 


What's My Address? If you are on a local machine, say monet, your address is 
youmame@monet.Berkeley.ARPA 

However, since most of the world does not have the new software in place yet, you will have to give 
correspondents slightly different addresses. From the ARPANET, your address would be: 

youmame%monet@Berkeley.ARPA 

From UUCP, your address would be: 

ucb vax ! monet. youmame 

Computer Center. The Berkeley Computer Center is in a subdomain of Berkeley so that they may adminis- 
ter their own name space. Messages to the computer center should be addressed to one of: 

user@host.CC.Berkeley.ARPA 

user%host.CC@Berkeley.ARPA 

depending on where the message is being sent from. The “.Berkeley. ARPA” may be omitted if the mes- 
sage is sent from inside Berkeley. 
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For the time being Computer Center hosts are known within the Berkeley domain, i.e., the “.CC” is 
optional. However, it is likely that this situation will change with time as both the Computer Science 
department and the Computer Center grow. 

Bitnet. Hosts on bitnet may be accessed using: 

user@host.BITNET 

This works from 4.2 machines. 
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NAME 

man - macros to typeset manual 
SYNOPSIS 

nroff -man file ... 

troff -man file... 

DESCRIPTION 

These macros are used to lay out pages of this manual. The best way to learn how to use the macros is to 
take an existing manual page and hack it over to your own requirements. 

Any text argument t may be zero to six words. Quotes may be used to include blanks in a ‘word’. If text is 
empty, the special treatment is applied to the next input line with text to be printed. In this way .1 may be 
used to italicize a whole line, or .SM followed by .B to make small bold letters. 

A prevailing indent distance is remembered between successive indented paragraphs, and is reset to default 
value upon reaching a non-indented paragraph. Default units for indents i are ens. 

Type font and size are reset to default values before each paragraph, and after processing font and size set- 
ting macros. 

These strings are predefined by -man: 

\*R *®\ ‘(Reg)’ in nroff. 

\*S Change to default type size. 

FILES 

/usr/lib/tmac/tmac.an 
SEE ALSO 

troff(l), nroff(l), man(l) 

BUGS 

Relative indents don’t nest. 


REQUESTS 




Request 

Cause If no 

Explanation 


Break 

Argument 

.B t 

no 

f=n.tl.* 

Text f is bold. 

.Bit 

no 

f=n.U. 

Join words of f alternating bold and italic. 

.BR t 

no 

f=n.tl. 

Join words of f alternating bold and Roman. 

.DT 

no 

.5i li... 

Restore default tabs. 

.HP i 

yes 

f=p.i.+ 

Set prevailing indent to i. Begin paragraph with hanging indent 

.If 

no 

f=n.t.l. 

Text f is italic. 

.IB t 

no 

f=n.t.l. 

Join words of f alternating italic and bold. 

.IPxi 

yes 

jc="" 

Same as .TP with tag x. 

.IR t 

no 

f=n.t.l. 

Join words of f alternating italic and Roman. 

!P 

yes 

- 

Same as .PP. 

PD d 

no 

d=. 4v 

Interparagraph distance is d. 

.PP 

yes 

- 

Begin paragraph. Set prevailing indent to .5i. 

.RE 

yes 

- 

End of relative indent. Set prevailing indent to amount of starting .RS. 

.RB t 

no 

f=n.t.l. 

Join words of f alternating Roman and bold. 

.Rif 

no 

f=n.t.l. 

Join words of f alternating Roman and italic. 

.RS i 

yes 

i=p.i. 

Start relative indent, move left margin in distance i. Set prevailing indent to .5i for 
nested indents. 

.SHf 

yes 

f=n.t.l. 

Subhead. 

.SM f 

no 

f=n.t.l. 

Text f is small. 

.TH n c xv m yes 

“ 

Begin page named n of chapter c; x is extra commentary, e.g. ‘local’, for page foot 
center; v alters page foot left, e.g. ‘4th Berkeley Distribution’; m alters page head 


Sun Release 3.0 Last change: 5 November 1984 


479 



MAN(7 ) 


TABLES 


MAN (7) 


center, e.g. ‘Brand X Programmer’s Manual’. Set prevailing indent and tabs to .5i. 
.TP i yes i=p.i. Set prevailing indent to i. Begin indented paragraph with hanging tag given by next 

text line. If tag doesn’t fit, place it on separate line. 

* n.Ll. = next text line; p.i. = prevailing indent 
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NAME 

me - macros for formatting papers 

SYNOPSIS 

nroff -me [ options ] file ... 
troff -me [ options ] file ... 

DESCRIPTION 

This package of nroff and troff macro definitions provides a canned formatting facility for technical papers 
in various formats. When producing 2-column output on a terminal, filter the output through col( 1). 

The macro requests are defined below. Many nroff and troff requests are unsafe in conjunction with this 
package, however these requests may be used with impunity after the first .pp: 

.bp begin new page 

.br break output line here 

.sp n insert n spacing lines 

.Is n (line spacing) n=l single, n=2 double space 

.na no alignment of right margin 

.ce n center next n lines 

.ul n underline next n lines 

.sz +n add n to point size 

Output of the eqn, neqn, refer, and tbl( 1) preprocessors for equations and tables is acceptable as input 

FILES 

/usr/lib/tmac/tmac.e 

/usr/lib/me/* 

SEE ALSO 

eqn(l), troff(l), refer(l), tbl(l) 

-me Reference Manual, Eric P. Allman 
Writing Papers with Nroff Using -me 

REQUESTS 

In the following list “initialization” refers to the first .pp, .lp, .ip, .np, .sh, or .uh macro. This list is incom- 
plete; see The -me Reference Manual for interesting details. 

Request Initial Cause Explanation 
Value Break 


.(c 

- 

yes 

Begin centered block 

•(d 

- 

no 

Begin delayed text 

•(f 

- 

no 

Begin footnote 

•(1 

- 

yes 

Begin list 

•(q 

- 

yes 

Begin major quote 

.(xx 

- 

no 

Begin indexed item in index x 

.(z 

- 

no 

Begin floating keep 

•)C 

- 

yes 

End centered block 

■)d 

- 

yes 

End delayed text 

•)f 

- 

yes 

End footnote 

•)1 

- 

yes 

End list 

•)q 

- 

yes 

End major quote 

•)x 

- 

yes 

End index item 

.)z 

- 

yes 

End floating keep 

.++ m H 


no 

Define paper section, m defines the part of the paper, and can be C (chapter), A (appen- 
dix), P (preliminary, e.g., abstract, table of contents, etc.), B (bibliography), RC (chapters 
renumbered from page one each chapter), or RA (appendix renumbered from page one). 

.+c T 

- 

yes 

Begin chapter (or appendix, etc., as set by .++). T is the chapter title. 

.lc 

1 

yes 

One column format on a new page. 
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.2c 

1 

yes 

Two column format. 

.EN 

- 

yes 

Space after equation produced by eqn or neqn. 

.EQxy 


yes 

Precede equation; break out and add space. Equation number is y. The optional argument 
x may be I to indent equation (default), L to left-adjust the equation, or C to center the 
equation. 

,TE 

- 

yes 

End table. 

.TH 

- 

yes 

End heading section of table. 

.TS* 

- 

yes 

Begin table; if x is H table has repeated heading. 

.ac A N 

- 

no 

Set up for ACM style output. A is the Author’s name(s), N is the total number of pages. 
Must be given before the first initialization. 

.b x 

no 

no 

Print x in boldface; if no argument switch to boldface. 

.ba +n 

0 

yes 

Augments the base indent by n. This indent is used to set the indent on regular text (like 
paragraphs). 

.be 

no 

yes 

Begin new column 

.bi* 

no 

no 

Print x in bold italics (nofill only) 

.bxx 

no 

no 

Print x in a box (nofill only). 

.ef 'x'y'z' 

"" 

no 

Set even footer to x y z 

.eh 'x'y'z' 


no 

Set even header to x y z 

.fo 'x'y'z' 

"" 

no 

Set footer to x y z 

.hx 

- 

no 

Suppress headers and footers on next page. 

.he 'x'y'z' 

"" 

no 

Set header to x y z 

.hi 

- 

yes 

Draw a horizontal line 

XX 

no 

no 

Italicize x; if x missing, italic text follows. 

.ipxy 

no 

yes 

Start indented paragraph, with hanging tag x. Indentation is y ens (default 5). 

•IP 

yes 

yes 

Start left-blocked paragraph. 

.lo 

- 

no 

Read in a file of local macros of the form ,*x. Must be given before initialization. 

.np 

1 

yes 

Start numbered paragraph. 

.of 'x'y'z' 

//// 

no 

Set odd footer to x y z 

.oh 'x'y'z 

//// 

no 

Set odd header to x y z 

.pd 

- 

yes 

Print delayed text. 

•PP 

no 

yes 

Begin paragraph. First line indented. 

.r 

yes 

no 

Roman text follows. 

.re 

- 

no 

Reset tabs to default values. 

.sc 

no 

no 

Read in a file of special characters and diacritical marks. Must be given before initializa- 


tion. 


.sh n x - yes Section head follows, font automatically bold, n is level of section, x is title of section, 

.sk no no Leave the next page blank. Only one page is remembered ahead. 

.sz +n lOp no Augment the point size by n points. 

.th no no Produce the paper in thesis format. Must be given before initialization. 

.tp no yes Begin title page. 

,ux - no Underline argument (even in troff). (Nofill only). 

.uh - yes Like .sh but unnumbered. 

.xp x - no Print index x. 
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NAME 

ms - text formatting macros 
SYNOPSIS 

nroff -ms [ options ] file ... 
troff -ms [ options ] file ... 

DESCRIPTION 

This package of nroff and troff macro definitions provides a formatting facility for various styles of arti- 
cles, theses, and books. When producing 2-column output on a terminal or lineprinter, or when reverse line 
motions are needed, filter the output through col{ 1). All external -ms macros are defined below. 

Note that this -ms macro package is an extended version written at Berkeley and is a superset of the stan- 
dard — ms macro packages as supplied by Bell Labs. Some of the Bell Labs macros have been removed; 
for instance, it is assumed that the user has little interest in producing headers stating that the memo was 
generated at Whippany Labs. 

Many nroff and troff requests are unsafe in conjunction with this package. However, the first four requests 
below may be used with impunity after initialization, and the last two may be used even before initializa- 
tion: 

.bp begin new page 

.br break output line 

.sp n insert n spacing lines 

.ce n center next n lines 

.Is n line spacing: n= 1 single, n=2 double space 

.na no alignment of right margin 

Font and point size changes with \f and \s are also allowed; for example, “\fIword\fR” will italicize word. 
Output of the tbl{ 1), eqn{ 1) and refer {l) preprocessors for equations, tables, and references is acceptable 
as input. 

FILES 

/usr/lib/tmac/tmac.s 

/usr/lib/ms/ms.??? 

SEE ALSO 

eqn(l), refer(l), tbl(l), troff(l) 

Formatting Documents with the —ms Macro Package in 
Editing and Text Processing on the Sun Workstation and the 
Beginner’s Guide to the Sun Workstation. 


REQUESTS 

Macro 

Initial 

Break? 

Explanation 

Name 

Value 

Reset? 


.AB x 

- 

y 

begin abstract; if x =no don’t label abstract 

.AE 

- 

y 

end abstract 

.AI 

- 

y 

author’s institution 

.AM 

- 

n 

better accent mark definitions 

.AU 

- 

y 

author’s name 

3x 

- 

n 

embolden x ; if no x , switch to boldface 

.Bl 

- 

y 

begin text to be enclosed in a box 

.B2 

- 

y 

end boxed text and print it 

.BT 

date 

n 

bottom title, printed at foot of page 

BXx 

- 

n 

print word x in a box 

.CM 

if t 

n 

cut mark between pages 

.CT 

- 

y.y 

chapter title: page number moved to CF (TM only) 

.DAx 

if n 

n 

force date x at bottom of page; today if no x 

.DE 


y 

end display (unfilled text) of any kind 
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.DS xy 

I 

y 

begin display with keep; .x=I,L,C,B; y=indent 

.ID y 

8n,.5i 

y 

indented display with no keep; y =indent 

.LD 

- 

y 

left display with no keep 

.CD 

- 

y 

centered display with no keep 

.BD 

- 

y 

block display; center entire block 

JEFx 

- 

n 

even page footer x (3 part as for .tl) 

.EHx 

- 

n 

even page header x (3 part as for .tl) 

.EN 

- 

y 

end displayed equation produced by eqn 

JEQxy 

- 

y 

break out equation; jc=L,I,C; y =equation number 

.FE 

- 

n 

end footnote to be placed at bottom of page 

.FP 

- 

n 

numbered footnote paragraph; may be redefined 

JFSx 

- 

n 

start footnote; x is optional footnote label 

HD 

undef 

n 

optional page header below header margin 

lx 

— 

n 

italicize x ; if no x, switch to italics 

.IPxy 

- 

y.y 

indented paragraph, with hanging tag x ; y =indent 

.IX xy 

— 

y 

index words x y and so on (up to 5 levels) 

.KE 

- 

n 

end keep of any kind 

.KF 

- 

n 

begin floating keep; text fills remainder of page 

.KS 

- 

y 

begin keep; unit kept together on a single page 

.LG 

- 

n 

larger; increase point size by 2 

.LP 

- 

y.y 

left (block) paragraph. 

.MCx 

- 

y.y 

multiple columns; *=column width 

.NDx 

if t 

n 

no date in page footer; x is date on cover 

.NHxy 

— 

y.y 

numbered header; x =level, x =0 resets, x=S sets to y 

.NL 

lOp 

n 

set point size back to normal 

.OFx 

- 

n 

odd page footer x (3 part as for .tl) 

.OH* 

- 

n 

odd page header x (3 part as for .tl) 

.PI 

if TM 

n 

print header on 1st page 

.PP 

- 

y.y 

paragraph with first line indented 

.PT 

- - 

n 

page title, printed at head of page 

.PXx 

- 

y 

print index (table of contents); x=no suppresses title 

•QP 

- 

y.y 

quote paragraph (indented and shorter) 

.R 

on 

n 

return to Roman font 

.RE 

5n 

y.y 

retreat: end level of relative indentation 

,RPx 

- 

n 

released paper format; x=no stops title on 1st page 

.RS 

5n 

y.y 

right shift: start level of relative indentation 

.SH 

- 

y.y 

section header, in boldface 

.SM 

— 

n 

smaller; decrease point size by 2 

.TA 

8n,5n 

n 

set tabs to 8n 16n ... (nroff) 5n lOn ... (troff) 

.TC* 

- 

y 

print table of contents at end; x =no suppresses title 

.TE 

- 

y 

end of table processed by tbl 

.TH 

- 

y 

end multi-page header of table 

.TL 

- 

y 

title in boldface and two points larger 

.TM 

off 

n 

UC Berkeley thesis mode 

.TSx 

- 

y.y 

begin table; if x=H table has multi-page header 

.ULx 

— 

n 

underline x , even in troff 

UXx 

— 

n 

UNIX; trademark message first time; x appended 

.XAxy 

— 

y 

another index entry; x=page or no for none; y =indent 

.XE 

— 

y 

end index entry (or series of .IX entries) 

,XP 

— 

y.y 

paragraph with first line exdented, others indented 

.XSxy 

- 

y 

begin index entry; x=page or no for none; y =indent 

.1C 

on 

y.y 

one column format, on a new page 

,2C 

- 

y.y 

begin two column format 
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•]- - n beginning of refer reference 

•[0 — n end of unclassifiable type of reference 

•[N - n N= Ljoumal-article, 2:book, 3:book-article, 4:report 
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REGISTERS 

Formatting distances can be controlled in -ms by means of built-in number registers. For example, this 
sets the line length to 6.5 inches: 

.nr LL 6.5i 

Here is a table of number registers and their default values: 


Name 

Register Controls 

Takes Effect Default 

PS 

point size 

paragraph 

10 

VS 

vertical spacing 

paragraph 

12 

LL 

line length 

paragraph 

6i 

LT 

title length 

next page 

same as LL 

FL 

footnote length 

next .FS 

5.5i 

PD 

paragraph distance paragraph 

lv (if n), ,3v (if t) 

DD 

display distance 

displays 

lv (if n), .5v (if t) 

PI 

paragraph indent 

paragraph 

5n 

QI 

quote indent 

next .QP 

5n 

FI 

footnote indent 

next .FS 

2n 

PO 

page offset 

next page 

0 (if n), ~li (if t) 

HM 

header margin 

next page 

li 

FM 

footer margin 

next page 

li 

FF 

footnote format 

next .FS 

0 (1, 2, 3 available) 


When resetting these values, make sure to specify the appropriate units. Setting the line length to 7, for 
example, will result in output with one character per line. Setting FF to 1 suppresses footnote superscript- 
ing; setting it to 2 also suppresses indentation of the first line; and setting it to 3 produces an .IP-like foot- 
note paragraph. 

Here is a list of string registers available in -ms; they may be used anywhere in the text: 


Name 

String’s Function 

\*Q 

quote (" in nr off, “ in troff) 

\*U 

unquote (" in nr off, ” in troff) 

\*- 

dash (- in nroff, — in troff) 

\*(MO 

month (month of the year) 

\*(DY 

day (current date) 


automatically numbered footnote 

\*' 

acute accent (before letter) 

\*' 

grave accent (before letter) 

\+* 

circumflex (before letter) 

\*, 

cedilla (before letter) 

\*: 

umlaut (before letter) 

\*- 

tilde (before letter) 


When using the extended accent mark definitions available with .AM, these strings should come after, 
rather than before, the letter to be accented. 

BUGS 

Floating keeps and regular keeps are diverted to the same space, so they cannot be mixed together with 
predictable results. 
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NAME 

intro - introduction to system maintenance and operation commands 
DESCRIPTION 

This section contains information related to system bootstrapping, operation and maintenance and 
describes all the server processes and daemons which run on the system. 

Disk formatting and labelling is done by diag{ 8S) which participates in most system bootstraps. Bootstrap- 
ping of the system is described in reboot (8). The standard set of commands run by the system when it 
boots is described in rc(8). Related commands include ones to check the consistency of file systems 
fsck( 8), mount and unmount file systems mount( 8) and umount(8), add swap devices swapon( 8), cause all 
outstanding disk I/O to complete sync (8), shutdown or reboot a running system shutdown (8), halt (8), and 
reboot (8), set the time on a machine from the time on another machine r date {8). 

Creation of file systems is discussed in mkfs( 8) and newfs(8). File system performance parameters are 
adjustable with tunefs(8). File system saves and restores are described in dump(8) and restore (8). 

Procedures for adding new users to a system are described in adduser(8) using vipw(8). 

Other programs useful when the system crashes or hardware is broken include gxtest{ 8S) which tests the 
frame buffer on a workstation, imemtest (8S) which tests the memory, crash (8 S) which describes what hap- 
pens when the system crashes, savecore(8) and analyze (8) which can be used to analyze system crash 
dumps. Occasionally useful as adjuncts to the fsck(8) file system repair program are clri(8), dcheck( 8), 
icheck(8), and ncheck{8). 

Configuring a new version of the UNIX kernel requires using the program config(8); major system 
bootstraps often require the use of mkproto( 8). New devices are made in the /dev directory when device 
drivers are added to the system by using the make dev {8) and mknod(8) commands. If you have source, 
you will use the install (8) command to reinstall freshly compiled programs, and catman(8 ) to reformat the 
pre-formatted version of the manual. 

Resource accounting is enabled by the accton(8 ) command, and summarized by sa(8). Login time 
accounting is performed by ac(8). 

A number of service and daemon processes are described here. The update { 8) daemon forces delayed disk 
I/O to occur and cron{ 8) runs periodic events (such as removing temporary files from the disk periodi- 
cally). The dmesg{ 8) process is invoked by cron and keeps the system error log. The init(8) process is the 
initial process created when UNIX boots and manages the reboot process and creates the initial login 
prompts on the various system terminals through the services of getty(8). The Internet super-server 
inetd{ 8C) invokes all other internet servers as needed. These servers include the remote shell servers 
rshd{ 8C) and rexecd (8C) the remote login server rlogind(8C) the FTP and TELNET daemons ftpd(8C) 
and telnetd( 8C), the TFTP daemon tftpd (8C) and the mail arrival notification daemon comsat (8C). Other 
network daemons include the Toad average/who is logged in’ daemon rwhod( 8C), the routing daemon 
routed^ 8C), and the mail daemon sendmail(8). 

If network protocols are being debugged, then the protocol debugging trace program trpt(8C) is often use- 
ful. Remote magnetic tape access is provided by rsh and rmt( 8C). Remote line printer access is provided 
by lpd( 8) and control over the various print queues is had through lpc( 8). Printer cost accounting is done 
through pac( 8). 

Network host tables may be gotten from the ARPA NIC using gettable (8C) and converted to UNIX usable 
format using htable(8). 

RCP and NFS daemons include: 

lect/portmap 

used by rpc based services. 
letc/ypbind 

used by the yellowpages to locate the yellowpages server. 

/etc/biod 
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used by NFS clients to read ahead to, and write behind from, network file systems. 

/ect/nfsd 

only on NFS servers, the server’s counterpart to /etc/biod, 
letclypserv 

implements the yellowpages server, typically on each nd server. 
lusr/etc/rpc.rstatd 

the server counterpart ofthe remote speedometer tools. 
lusr/etc.mountd 

the server counterpart to mount . 

/usr/etc/rcp.rwalld 

used for broadcasting messages over the network. 


LIST OF PROGRAMS 

Program Appears on Page 

Description 

ac 

ac.8 

login accounting 

accton 

sa.8 

system accounting 

adbgen 

adbgen.8 

generate adb script 

adduser 

adduser.8 

procedure for adding new users 

analyze 

analyze.8 

Virtual UNIX postmortem crash analyzer 

arp 

arp.8c 

address resolution display and control 

catman 

catman.8 

create the cat files for the manual 

chown 

chown.8 

change owner 

clri 

clri.8 

clear i-node 

comsat 

comsat.8c 

biff server 

config 

config.8 

build system configuration files 

crash 

crash.8s 

what happens when the system crashes 

cron 

cron.8 

clock daemon 

dcheck 

dcheck.8 

file system directory consistency check 

diag 

diag.8s 

General-purpose stand-alone utility package 

dmesg 

dmesg.8 

collect system diagnostic messages to form error log 

dump 

dump.8 

incremental file system dump 

dumpfs 

dumpfs. 8 

dump file system information 

fastboot 

fastboot.8 

reboot/halt the system without checking the disks 

fasthalt 

fastboot.8 

reboot/halt the system without checking the disks 

fsck 

fsck.8 

file system consistency check and interactive repair 

ftpd 

ftpd.8c 

DARPA Internet File Transfer Protocol server 

gettable 

gettable.8c 

get NIC format host tables from a host 

getty 

getty.8 

set terminal mode 

gxtest 

gxtest.8s 

stand alone test for the Sun video graphics board 

halt 

halt.8 

stop the processor 

htable 

htable.8 

convert NIC standard format host tables 

icheck 

icheck.8 

file system storage consistency check 

ifconfig 

ifconfig.8c 

configure network interface parameters 

imemtest 

imemtest.8s 

stand alone memory test 

inetd 

inetd.8c 

internet services daemon 

init 

init.8 

process control initialization 

iostat 

iostat.8 

report I/O statistics 

kgmon 

kgmon.8 

generate a dump of the operating system’s profile buffers 

lpc 

lpc.8 

line printer control program 

lpd 

lpd.8 

line printer daemon 

MAKEDEV 

makedev.8 

make system special files 

makekey 

makekey .8 

generate encryption key 
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mkfs 

mkfs.8 

construct a file system 

mknod 

mknod. 8 

build special file 

mkproto 

mkproto.8 

construct a prototype file system 

mount 

mount.8 

mount and dismount file system 

ncheck 

ncheck.8 

generate names from i-numbers 

nd 

nd.8c 

network disk control 

netstat 

netstat.8 

show network status 

newaliases 

newaliases.8 

rebuild the data base for the mail aliases file 

newfs 

newfs.8 

construct a new file system 

pac 

pac.8 

printer/plotter accounting information 

pstat 

pstat.8 

print system facts 

quot 

quot.8 

summarize file system ownership 

rc 

rc.8 

command script for auto-reboot and daemons 

rdate 

rdate.8 

set system date from a remote host 

reboot 

reboot.8 

UNIX bootstrapping procedures 

renice 

renice.8 

alter priority of running processes 

restore 

restore.8 

incremental file system restore 

rexecd 

rexecd.8c 

remote execution server 

rlogind 

rlogind.8c 

remote login server 

rmail 

rmail. 8 

handle remote mail received via uucp 

rmt 

rmt.8c 

remote magtape protocol module 

route 

route.8c 

manually manipulate the routing tables 

routed 

routed.8c 

network routing daemon 

rshd 

rshd.8c 

remote shell server 

rwhod 

rwhod.8c 

system status server 

sa 

sa.8 

system accounting 

savecore 

savecore.8 

save a core dump of the operating system 

sendmail 

sendmail.8 

send mail over the internet 

shutdown 

shutdown.8 

close down the system at a given time 

sticky 

sticky.8 

executable files with persistent text 

swapon 

swapon.8 

specify additional device for paging and swapping 

sync 

sync.8 

update the super block 

syslog 

syslog.8 

log systems messages 

telnetd 

telnetd.8c 

DARPA TELNET protocol server 

tftpd 

tftpd.8c 

DARPA Trivial File Transfer Protocol server 

timed 

timed.8c 

DARPA Time server 

trpt 

trpt.8c 

transliterate protocol trace 

tunefs 

tunefs.8 

tune up an existing file system 

umount 

mount.8 

mount and dismount file system 

update 

update.8 

periodically update the super block 

uuclean 

uuclean.8c 

uucp spool directory clean-up 

vipw 

vipw.8 

edit the password file 

vmstat 

vmstat.8 

report virtual memory statistics 
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NAME 

ac - login accounting 

SYNOPSIS 

/usr/etc/ac [ -w wtmp ] [ -p ] [ -d ] [ people ] ... 

DESCRIPTION 

Ac produces a printout giving connect time for each user who has logged in during the life of the current 
wtmp file. A total is also produced. 

The accounting file lusrladmlwtmp is maintained by init and login. Neither of these programs creates the 
file, so if it does not exist no connect-time accounting is done. To start accounting, it should be created 
with length 0. On the other hand if the file is left undisturbed it will grow without bound, so periodically 
any information desired should be collected and the file truncated. 

OPTIONS 

-w specifies an alternate wtmp file. 

-p prints individual totals; without this option, only totals are printed. 

-d printout for each midnight to midnight period. Any people will limit the printout to only the 
specified login names. If no wtmp file is given, lusrladmlwtmp is used. 

FILES 

/usr/adm/wtmp 
SEE ALSO 

init(8), sa(8), login(l), utmp(5). 
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NAME 

adbgen - generate adb script 
SYNOPSIS 

/usr/Iib/adb/adbgen file.adb ... 

DESCRIPTION 

Adbgen makes it possible to write adb(l) scripts that do not contain hard-coded dependencies on structure 
member offsets. The input to adbgen is a file named file Adb which contains adbgen header information, 
then a null line, then the name of a structure, and finally an adb script Adbgen only deals with one struc- 
ture per file; all member names are assumed to be in this structure. The output of adbgen is an adb script in 
file. Adbgen operates by generating a C program which determines structure member offsets and sizes, 
which in turn generates the adb script. 

The header lines, up to the null line, are copied verbatum into the generated C program. Typically these 
include C #include statements to include the header files containing the relevant structure declarations. 

The adb script part may contain any valid adb commands (see adb 1 1)), and may also contain adbgen 
requests, each enclosed in (}s. Request types are: 

1 Print a structure member. The request form is {member format}. Member is a member name of 
the structure given earlier, and format is any valid adb format request For example, to print the 
p _pid field of the proc structure as a decimal number, you would write {p_pid,d}. 

2 Reference a structure member. The request form is {* member, base}. Member is the member 
name whose value is desired, and base is an adb register name which contains the base address of 
the structure. For example, to get the p _pid field of the proc structure, you would get the proc 
structure address in an adb register, say <f, and write {*p_pid,<f}- 

3 Tell adbgen that the offset is ok. The request form is {OFFSETOK}. This is useful after invok- 
ing another adb script which moves the adb dot. 

4 Get the size of the structure. The request form is {SIZEOF}. Adbgen replaces this request with 
the size of the structure. This is useful in incrementing a pointer to step through an array of struc- 
tures. 

5 Get the offset to the end of the structure. The request form is {END}. This is useful at the end of 
the structure to get adb to align the dot for printing the next structure member. 

Adbgen keeps track of the movement of the adb dot and emits adb code to move forward or backward as 
necessary before printing any structure member in a script Adbgen' s model of the behavior of adb' s dot 
is simple: it is assumed that the first line of the script is of the form struct address! adb text and that subse- 
quent lines are of the form +/adb text. This causes the adb dot to move in a sane fashion. Adbgen does 
not check the script to ensure that these limitations are met. Adbgen also checks the size of the structure 
member against the size of the adb format code and warns you if they are not equal. 

EXAMPLE 

If there were an include file x.h which contained: 

struct x { 

char *x_cp; 

char x_c; 

int x_i; 

}; 

Then an adbgen file (call it script.adb) to print it would be: 

#include "x.h" 
x 

/’x_cp"16t"x_c"8t"x_i"n{x_cp,X}{x_c,C}{x_i,D} 
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After running adbgen the output file script would contain: 

7"x_cp"16t"x_c"8t"x_i"nXC+D 
To invoke the script you would type: 

x$<script 

DIAGNOSTICS 

Warnings about structure member sizes not equal to adb format items and complaints about badly format- 
ted requests. The C compiler complains if you reference a structure member that does not exist. It also 
complains about & before array names; these complaints may be ignored. 

FILES 

/usr/lib/adb/* adb scripts for debugging the kernel 
SEE ALSO 

adb(l). Using ADB to Debug the UNIX Kernel 

BUGS 

Adb syntax is ugly; there should be a higher level interface for generating scripts. 

Structure members which are bit fields cannot be handled because C will not give the address of a bit field. 
The address is needed to determine the offset 
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NAME 

adduser - procedure for adding new users 
DESCRIPTION 

To add a new user account to the system, you must do at least the following things: 

1. Create an entry in the system password file for that user. 

2. Make a ‘home directory’ for the user and make sure that the user is the owner of their home direc- 
tory. 

3. Set up some skeletal profile files for the new user. 

These steps are described in detail below. 

Making an entry in the password file: A new user must choose a login name, which must not 
already appear in letclpasswd. An account can be added by editing a line into the letc/passwd file; this must 
be done with the password file locked, for example, by using vipw{ 8). 

A new user is given a group and user id. User id’s should be distinct across a system, since they are used 
to control access to files. Typically, users working on similar projects will be put in the same group. Sys- 
tem staff is group ‘10’ for historical reasons, and the super-user is in this group. 

A skeletal account for a new user ‘francine’ would look like: 

francine : : 235 : 20 : & Featherstonehaugh : /usr/francine : /bin/csh 

Fields in the password file have the following meanings: 

1. Login name (‘francine’). The login name is limited to eight characters in length. 

2. Encrypted password. Typically, this field is left empty for a new user so that the first time they log in 
they don’t need a password. They can then set their password to whatever they like using the 
passwd( 1) command. 

3. User ID. The user ID is a number which identifies that user uniquely in the system. All files that that 
user creates have this number stored in the data block that describes the file and commands such as 
ls(l) use that number to look in the password file to get the user’s name when identifying the owner of 
the file. For this reason, you cannot just go merrily changing this number at random. 

4. Group ID. The group ID is a number which identifies the group to which the user belongs. All files 
that that user creates have this number stored in the data block that describes the file and commands 
such as /s(l) use that number to look in the groups file to get the groups name when identifying the 
group ownership of the file. 

5. This field is called the ‘GCOS’ field (from earlier implementation of the UNIX system) and is tradition- 
ally used to hold the user’s full name. Some installations have other information encoded in this field. 
From this information we can tell that Francine’s real name is ‘Francine Featherstonehaugh’. The & 
here is a shorthand for the user’s login name. 

6. User’s home directory. This is the directory in which that user is ‘positioned’ when they log in. 

7. Initial shell which this user will see on login. If this field is empty, sh(l) is used as the initial shell. 

Making a home directory for the new user : now you make a home directory for Francine. As 
shown in the password file entry above, Francine’s home directory is /usr/francine . Francine must be the 
owner of that directory in order to create files there. So the following sequence would suffice: 
tutorial# mkdir /usr/francine 
tutorial# /etc/chown francine /usr/francine 
tutorial# 

Setting up skeletal profile files : It is useful to give new users some help in getting started, supplying 
them with a few skeletal files such as .profile if they use Ibin/sh as the shell, or .cshrc and .login if they use 
/bin/csh as the shell. New users should be given copies of these files which, for instance, arrange to use 
tset(l) automatically at each login. 
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FILES 

/etc/passwd password file 

SEE ALSO 

passwd(I), mkdir(l), chown(8), chsh(l), passwd(5), vipw(8) 


494 


Last change: 11 October 1984 


Sun Release 3.0 



ANALYZE ( 8 ) 


MAINTENANCE COMMANDS 


ANALYZE (8) 


NAME 

analyze - Virtual UNIX postmortem crash analyzer 
SYNOPSIS 

/usr/etc/analyze [ -s swapfile ] [ — f ] [ — m ] [ — d ] [ — D ] [ — v ] corefile [ system ] 

DESCRIPTION 

Analyze is the post-mortem analyzer for the state of the paging system. In order to use analyze you must 
arrange to get a image of the memory (and possibly the paging area) of the system after it crashes (see 
crash^S)). 

The analyze program reads the relevant system data structures from the core image file and indexing infor- 
mation from /vmunix (or the specified file) to determine the state of the paging subsystem at the point of 
crash. It looks at each process in the system, and the resources each is using in an attempt to determine 
inconsistencies in the paging system state. Normally, the output consists of a sequence of lines showing 
each active process, its state (whether swapped in or not), its pObr, and the number and location of its page 
table pages. Any pages which are locked while raw i/o is in progress, or which are locked because they are 
intransit are also printed. (Intransit text pages often diagnose as duplicated; you will have to weed these 
out by hand.) 

The program checks that any pages in core which are marked as not modified are, in fact, identical to the 
swap space copies. It also checks for non-overlap of the swap space, and that the core map entries 
correspond to the page tables. The state of the free list is also checked. 

Options to analyze: 

-D causes the diskmap for each process to be printed. 

-d causes the (sorted) paging area usage to be printed. 

-f which causes the free list to be dumped. 

-m causes the entire coremap state to be dumped. 

-v (long unused) which causes a hugely verbose output format to be used. 

In general, the output from this program can be confused by processes which were forking, swapping, or 
exiting or happened to be in unusual states when the crash occurred. You should examine the flags fields 
of relevant processes in the output of a pstat{ 8) to weed out such processes. 

It is possible to look at the core dump with adb if you do 

adb -k /vmunix /vmcore 

FILES 

/vmunix default system namelist 
SEE ALSO 

adb(lS), ps(l), crash(8S), pstat(8) 

DIAGNOSTICS 

Various diagnostics about overlaps in swap mappings, missing swap mappings, page table entries incon- 
sistent with the core map, incore pages which are marked clean but differ from disk-image copies, pages 
which are locked or intransit, and inconsistencies in the free list. 

It would be nice if this program analyzed the system in general, rather than just the paging system in partic- 
ular. 
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NAME 

arp - address resolution display and control 

SYNOPSIS 

arp hostname 

arp -a [ vmunix [ kmem ] ] 

arp -d hostname 

arp -s hostname ether addr [ temp ] [ pub ] 
arp -f filename 

DESCRIPTION 

The arp program displays and modifies the Intemet-to-Ethemet address translation tables used by the 
address resolution protocol 

OPTIONS 

With no flags, the program displays the current ARP entry for hostname. 

-a display all of the current ARP entries by reading the table from the file kmem (default /dev/kmem) 
based on the kernel file vmunix (default /vmunix). 

-d a super-user may delete an entry for the host called hostname. 

-s create an ARP entry for the host called hostname with the Ethernet address ether addr. The Ether- 
net address is given as six hex bytes separated by colons. The entry will be permanent unless the 
word temp is given in the command. If the word pub is given, the entry will be published, e.g., 
this system will respond to ARP requests for hostname even though the hostname is not its own. 

-f read filename and set multiple entries in the ARP tables. Entries in the file should be of the form 

hostname ether addr [ temp ] [ pub ] 
with argument meanings as given above. 

SEE ALSO 

arp(4p), ifconfig(8c) 
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NAME 

catman - create the cat files for the manual 
SYNOPSIS 

/usr/etc/catman [ -p ] [ -n ] [ -w ] [ sections ] 

DESCRIPTION 

Catman creates the preformatted versions of the on-line manual from the nroff input files. Each manual 
page is examined and those whose preformatted versions are missing or out of date are recreated. If any 
changes are made, catman recreates the /usr/man/whatis database. 

If there is one parameter not starting with a it is take to be a list of manual sections to look in. For 
example 

catman 123 

only updates manual sections 1, 2, and 3. 

OPTIONS 

-n Do not create /usr/man/whatis. 

-p Print what would be done instead of doing it 

-w Only create the /usr/man/whatis database. No manual reformatting is done. 

FILES 

/usr/man/man?/*.* raw (nroff input) manual sections 

/usr/man/cat?/*.* preformatted manual pages 

/usr/lib/makewhatis commands to make whatis database 

SEE ALSO 

man(l) 
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NAME 

chown - change owner 
SYNOPSIS 

/etc/chown -f owner file . • . 

DESCRIPTION 

Chown changes the owner of the files to owner. The owner may be either a decimal UID or a login name 
found in the password file. 

Only the super-user can change owner, in order to simplify as yet unimplemented accounting procedures. 
OPTIONS 

-f Do not report errors . 

FILES 

/etc/passwd 
SEE ALSO 

chgrp(l), passwd(5), group(5) 
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NAME 

clri - clear i-node 
SYNOPSIS 

/etc/clri filesystem i-number ... 

DESCRIPTION 

N.B.: Clri is obsoleted for normal file system repair work by fsck(8). 

Clri writes zeros on the i-nodes with the decimal i-numbers on the filesystem. After clri, any blocks in the 
affected file will show up as ‘missing’ in an icheck{8) of the filesystem. 

Read and write permission is required on the specified file system device. The i-node becomes allocatable. 

The primary purpose of this routine is to remove a file which for some reason appears in no directory. If it 
is used to zap an i-node which does appear in a directory, care should be taken to track down the entry and 
remove it. Otherwise, when the i-node is reallocated to some new file, the old entry will still point to that 
file. At that point removing the old entry will destroy the new file. The new entry will again point to an 
unallocated i-node, so the whole cycle is likely to be repeated again and again. 

SEE ALSO 

icheck(8) 

BUGS 

If the file is open, clri is likely to be ineffective. 
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NAME 

comsat - biff server 

SYNOPSIS 

/usr/etc/in.comsat 

DESCRIPTION 

Comsat is the server process which listens for reports of incoming mail and notifies users who have 
requested to be told when mail arrives. It is invoked as needed by inetd(8C), and times out if inactive for a 
few minutes. 

Comsat listens on a datagram port associated with the “biff’ service specification (see services ( 5)) for one 
line messages of the form 

user@ mailbox-offset 

If the user specified is logged in to the system and the associated terminal has the owner execute bit turned 
on (by a “biff y”), the offset is used as a seek offset into the appropriate mailbox file and the first 7 lines or 
560 characters of the message are printed on the user’s terminal. Lines which appear to be part of the mes- 
sage header other than the “From”, “To”, “Date”, or “Subject” lines are not printed when displaying 
the message. 

FILES 

/etc/utmp to find out who’s logged on and on what terminals 

SEE ALSO 

biff(l) 

BUGS 

The message header filtering is prone to error. 

The notification should appear in a separate window so it does not mess up the screen. 
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NAME 

config - build system configuration files 
SYNOPSIS 

/etc/config [ -p ] [ -n ] [ -f ] [ -o obj_dir ] config Jle 
DESCRIPTION 

Config does the preparation necessary for building a new system kernel with make(l). The config Jile 
named on the command line describes the kernel to be made in terms of options you want in your system, 
size of tables, and device drivers to be included. When you run config, it uses several input files located in 
the current directory (typically the conf subdirectory of the system source including your config Jile). The 
format of this file is described below. The following options are understood by config. 

-p Configures the system for profiling (see kgmon (8) and gprof(l)). 

— n Do not do the "make depend". Normally config will do the "make depend" automatically. If 

this option is used config will print “Don't forget to do a "make depend"” before completing 
as a reminder. 

Set up the makefile for fast builds. This is done by building a " vmunix.o" file which includes 
all the .o files which there is no source. This reduces the number of files which have to be 
stat’ed during a system build. This is done by prelinking all the files for which no source 
exists into another file which is then linked in place of all these files when the kernel is made. 
This makefile is faster because it does not stat the object files during the build. 

Use .Jobj_dir instead of ../OBJ as the directory to find the object files when the correspond- 
ing source file is not present in order to generate the files necessary to compile and link your 
kernel. 

If the directory named J config Jile does not exist, config will create one. One of config ’ s output files is a 
makefile which you use with make to build your system. For a description of other input and output files, 
see the FILES section below. 

You use config as follows. Run config from the conf subdirectory of the system source (in a typical Sun 
environment, from / syslconf ): 

tutorial# /etc/config config Jle 
Doing a "make depend" 
tutorial# cd J config Jle 
tutorial# make 
...lots of output- 

While config is running watch for any errors. Never use a kernel which config has complained about; the 
results are unpredictable. If config completes successfully, you can change directory to the Jconfigjle 
directory, where it has placed the new makefile, and use make to build a kernel. The output files placed in 
this directory include ioconf.c, which contains a description of I/O devices attached to the system; 
mbglue.s, which contains short assembly language routines used for vectored interrupts, a makefile, which 
is used by make to build the system; a set of header files {device jiame.h) which contain the number of 
various devices that may be compiled into the system; and a set of swap configuration files which contain 
definitions for the disk areas to be used for the root file system, swapping, and system dumps. 

Now you can install your new kernel and try it out. 

CONFIG FILE FORMAT 

In the following descriptions, a number can be a decimal integer, a whole octal number or a whole hexade- 
cimal number. Hex and octal numbers are specified to config in the same way they are specified to the C 
compiler, a number starting with "Ox" is a hex number and a number starting with just a "0" is an octal 
number. You can use a floating-point number to specify half-hour time zones. 


-f 


-o obj dir 
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Comments are specified in a config file with the character "#". All characters from a "#" to the end of a 
line are ignored. 

Lines beginning with tabs are considered continuations of the previous line. 

Lines of the configuration file can be one of two basic types. First, there are lines which describe general 
things about your system: 

machine type 

This is system is to run on the machine type specified. Only one machine type can appear in the 
config file. The legal types for a Sun system are "sun2" and "sun3" (note that the double quotes are 
part of the designation). 

cpu "type" 

This system is to run on the cpu type specified. More than one cpu type can appear in the config file. 
Legal types for a "sun2" machine are "SUN2_120" (generic for any Multibus based Sun-2 machine), 
"SUN2_50" (generic for any VMEbus based Sun-2 machine), The legal types for a "sun3" machine 
are "SUN3_160", and ”SUN3_50". 

ident name 

Gives the system identifier — a name for the machine or machines that run this kernel, name must 
be enclosed in double quotes if it contains both letters and numbers (for example, "SDST120"), or 
you will get a syntax error when you run letc/config. Also, note that if name is GENERIC, you can 
specify the unique config_clau.se swap generic in the config line described below. If you use any 
other string for name, and you also include an options GENERIC line, you can still use the swap 
generic line. However, if you use any other string for name and omit the options GENERIC line, 
config will set up the makefile as if you had. 

timezone number ( dst ] 

Specifies the timezone you are in, measured in the number of hours west of GMT. 5 is EST, 8 is 
PST. Negative numbers indicate hours east of GMT. If you specify dst, the system will convert to 
and from daylight savings time when appropriate. 

maxusers number 

The maximum expected number of simultaneously active user on this system is number. This 
number is used to size several system data structures. 

options optlist 

Compile the listed options into the system. Options in this list are separated by commas. A line of 
the form "options FUNNY, HAHA" yields -DFUNNY -DHAHA to the C compiler. An option may 
be given a value, by following its name with "=" then the value enclosed in (double) quotes. None of 
the standard options use such a value. 

In addition, options can be used to bring in additional files if the option is listed in the files files. All 
options should be listed in upper case. In this case, no corresponding option. h will be created as it 
would be using the corresponding pseudo-device method. 

config sysname config_clauses... 

Generate a system with name sysname and configuration as specified in config-clauses . The 
sysname is used to name the resultant binary image and per-system swap configuration files. The 
config clauses indicate the location for the root file system, one or more disk partitions for swapping 
and paging, and a disk partition to which system dumps should be made. All but the root device 
specification may be omitted; config will assign default values as described below. 

root A root device specification is of the form root on xyOd. If a specific partition is omitted — 
for example, if only root on xyO is specified — the “a” partition is assumed. When a gen- 
eric system is being built, no root specification should be given; the root device will be 
defined at boot time by prompting the console. 

swap Swap device specifications have two possible forms. If a generic swap configuration is 
required, the clause swap generic should be specifed. Otherwise, if a single partition is to 
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be used for swapping, one may specify swap on xyOb. If multiple partitions are to be inter- 
leaved one should specify something of the form swap on xyO and xyl and xylg. If no 
swap specification is given, config assumes swapping should be done on the “b” partition 
of the root device. Swapping areas may be almost any size and multiple swap partitions of 
varying size may be interleaved. Partitions used for swapping are sized at boot time by the 
system; to override dynamic sizing of a swap area the number of sectors in the swap area 
can be specified in the config file. For example, swap on xyOb size 99999 would configure 
a swap partition with 99999 sectors. 

dumps The location to which system dumps are sent may be specified with a clause of the form 
dumps on xyl. If no dump device is specified, the first swap partition specified is used. If a 
device is specified without a particular partition, the “b” partition is assumed. If a generic 
configuration is to be built, no dump device should be specified; the dump device will be 
assigned to the swap device dynamically configured at boot time. 

Dumps are placed at the end of the partition specified. Their size and location is recorded in 
global kernel variables dumpsize and dumplo , respectively, for use by savecore( 8). 

Device names specified in configuration clauses are mapped to block device major numbers with the 
file devices. machine, where machine is the machine type previously specified in the configuration 
file. If a device name to block device major number mapping must be overridden, a device 
specification may be given in the form major x minor y. 

The second group of lines in the configuration file describe which devices your system has and what they 
are connected to (for example, I have a Xylogics 450 Disk Controller at address 0xee40 in the Multibus I/O 
space). These lines have the following format: 

devjype devjiame at con_dev more_info 

Dev type is either tape, disk, controller, device, or pseudo-device. These types have the following mean- 
ings: 

controller 

is a disk or tape controller, 
disk or tape 

are devices connected to a controller, 
device 

is something ‘attached’ to the main system bus, like a cartridge tape interface, 
pseudo-device 

A software subsystem or driver treated like a device driver, but without any associated 
hardware. Current examples are the pseudo-tty driver and various network subsystems. For 
pseudo-devices, more_info may be specified as an integer, that gives the value of the sym- 
bol defined in the header file created for that device, and is generally used to indicate the 
number of instances of the pseudo-device to create. 

Dev name is the standard UNIX device name and unit number (if the device is not a psuedo-device) of the 
device you are specifying. For example, xycO is the devjiame for the first Xylogics controller in a system; 
arO names the first quarter-inch tape controller. 
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Conjtev is what the device you are specifying is connected to. It is either nexus?, a bus type, or a con- 
troller. There are several bus types which are used by config and the kernel. 

The different possible bus types are: 


virtual 

Virtual preset 

obmem 

On board memory 

obio 

On board io 

mbmem 

Multibus memory (sun2 only) 

mbio 

Multibus io (sun2 only) 

vmel6dl6 (vmel6) 

16 bit VMEbus/ 16 bit data 

vme24dl6 (vme24) 

24 bit VMEbus/ 16 bit data 

vme32dl6 

32 bit VMEbus/ 16 bit data (sun3 only) 

vmel6d32 

16 bit VMEbus/ 32 bit data (sun3 only) 

vme24d32 

24 bit VMEbus/ 32 bit data (sun3 only) 

vme32d32 (vme32) 

32 bit VMEbus/ 32 bit data (sun3 only) 


All of these bus types are declared to be connected to nexus. The devices are hung off these buses. If the 
bus is wildcarded, then the autoconfiguation code will determine if it is appropriate to probe for the device 
on the machine that it is running on. If the bus is numbered, then the autoconfiguation code will only look 
for that device on machine type N. In general, the Multibus and VMEbus bus types are always wildcarded. 

More_info is a sequence of the following: 

csr addr 

Specifies the address of the csr (command and status registers) for a device. The csr 
addresses specified for the device are the addresses within the bus type specified. 

The csr address must be specified for all controllers, and for all devices connected to a main 
system bus. 

drive number 

For a disk or tape, specifies which drive this is. 
flags number 

These flags are made available to the device driver, and are usually read at system initializa- 
tion time. 

priority level 

For devices which interrupt, specifies the interrupt level at which the device operates, 
vector intr number [ intr number . . . ] 

For devices which use vectored interrupts on VMEbus systems, intr specifies the vectored 
interrupt routine and number the corresponding vector to be used (64-255). 

A ? may be substituted for a number in two places and the system will figure out what to fill in for the ? 
when it boots. You can put question marks on a con_dev (for example, at virtual ?), or on a drive number 
(for example, drive ?). This allows redundancy, as a single system can be built which will boot on different 
hardware configurations. 

The easiest way to understand config files it to look at a working one and modify it to suit your system. 
Good examples are provided in the Configuring the System Kernel chapter and second appendix of the 
Installing UNIX on the Sun Workstation manual. 

FILES 
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Files in Isys/conf which may be useful for developing the configjile used by config are: 

GENERIC These are generic configuration files for 

either a Sun-2 or Sun-3 system. 

They contain all possible device 
descriptions lines for the particular 
architecture. 


README File describing how to make a new kernel 

As shipped from Sun, the files used by ! etc! config as input are in the /sys/conf directory: 


configjile 

makefile.sun[23] 

files 

files, sun [23] 
devices.sun[23] 


System-specific configuration file 

Generic prototype makefile for Sun-[23] systems 

List of common files required to build a basic kernel 

List of files for a Sun-[23] specific kernel 

Name to major device mapping file for Sun-[23] systems 


/etc! config places its output files in the J configjile directory: 


mbglue.s Short assembly language routines used for vectored interrupts 

ioconf.c Describes I/O devices attached to the system 

makefile Used with make (1) to build the system 

device jiame.h A set of header files (various device name ’s) containing devices 
which can be compiled into the system. 


SEE ALSO 

The SYNOPSIS portion of each device entry in the Section 4 pages of the System Interface Manual. 

In the Installing UNIX on the Sun Workstation Manual, see the Configuring the System Kernel chapter, and 
the Sample Configuration Files appendix. 
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NAME 

crash - what happens when the system crashes 

DESCRIPTION 

This section explains what happens when the system crashes and how you can analyze crash dumps. 

When the system crashes voluntarily it displays a message of the form 
panic: why i gave up the ghost 

on the console, takes a dump on a mass storage peripheral, and then invokes an automatic reboot procedure 
as described in reboot (8). Unless some unexpected inconsistency is encountered in the state of the file sys- 
tems due to hardware or software failure the system will then resume multi-user operations. 

The system has a large number of internal consistency checks; if one of these fails, it will panic with a very 
short message indicating which one failed. 

The most common cause of system failures is hardware failure, which can reflect itself in different ways. 
Here are the messages which you are likely to encounter, with some hints as to causes. Left unstated in all 
cases is the possibility that hardware or software error produced the message in some unexpected way. 

IO err in push 
hard IO err in swap 

The system encountered an error trying to write to the paging device or an error in reading critical 
information from a disk drive. You should fix your disk if it is broken or unreliable. 

timeout table overflow 

This really shouldn’t be a panic, but until we fix up the data structure involved, running out of 
entries causes a crash. If this happens, you should make the timeout table bigger by changing the 
value of ncallout in the param.c file, and then rebuild your system. 

trap type type, pid process-id, pc = program-counter, sr = status-register, context context-number 
A unexpected trap has occurred within the system; typical trap types are: 

• Bus error 

• Address error 

• Illegal instruction 

• Divide by zero 

• Chk instruction 

• Trapv instruction 

• Privilege violation 

• Trace 

• 1010 emulator trap 

• 1111 emulator trap 

• Stack format error 

• Unitialized interrupt 

• Spurious interrupt 

The favorite trap types in system crashes are ‘Bus error’ or ‘Address error’, indicating a wild 
reference. The process-id is the id of the process running at the time of the fault, program- 
counter is the hexadecimal value of the program counter, status-register is the hexadecimal value 
of the status register, and context-number is the context that the process was running in. These 
problems tend to be easy to track down if they are kernel bugs since the processor stops cold, but 
random flakiness seems to cause this sometimes. 

init died 

The system initialization process has exited. This is bad news, as no new users will then be able 
to log in. Rebooting is the only fix, so the system just does it right away. 

That completes the list of panic types you are likely to see. 
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When the system crashes it writes (or at least attempts to write) an image of memory into the back end of 
the primary swap area. After the system is rebooted, the program savecore( 8) runs and preserves a copy of 
this core image and the current system in a specified directory for later perusal. See savecore{ 8) for 
details. 

To analyze a dump you should begin by running adb( IS) with the -k flag on the core dump. A more com- 
plete discussion of system debugging is impossible here. See, however, ‘Using ADB to Debug the UNIX 
Kernel’. 

SEE ALSO 

adb(lS), analyze(8), reboot(8) 

Using ADB to Debug the UNIX Kernel, in the System Internals for the Sun Workstation 
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NAME 

cron - clock daemon 

SYNOPSIS 

/etc/cron 

DESCRIPTION 

Cron executes commands at specified dates and times according to the instructions in the file 
lusrlliblcrontab. Since cron never exits, it should only be executed once. This is best done by running 
cron from the initialization process through the file letclrc\ see init( 8). 

lusrlliblcrontab consists of lines of six fields each. The fields are separated by spaces or tabs. The first five 
are integer patterns to specify the minute (0-59), hour (0-23), day of the month (1-31), month of the year 
(1-12), and day of the week (1-7 with l=Monday). Each of these patterns may contain a number in the 
range above; two numbers separated by a dash meaning a range inclusive; a list of numbers separated by 
commas meaning any of the numbers; or an asterisk meaning all legal values. The sixth field is a string 
that is executed by the shell at the specified times. A percent character in this field is translated to a new- 
line character. Only the first line (up to a % or end of line) of the command field is executed by the shell. 
The other lines are made available to the command as standard input. 

Here are a few example lines from lusrlliblcrontab, to give you a better sense of the file’s format: 

0 0 * * * calendar - 

15 0 * * * /usr/etc/sa -s >/dev/null 

0,30 * * * * /etc/dmesg - »/usr/adm/messages 

15 4 * * * find /usr/preserve -mtime +7 -a -exec rm -f {} ; 

10 4 * * * egrep ’SYSERR|refused|unreachable’ /usr/spool/log/syslog.O |mail Postmaster 
Cron examines lusrlliblcrontab under the following conditions: 

• At least once per hour (on the hour). 

• When the next command is to be run — cron looks ahead until the next command and sleeps until then. 

• When cron’s process is sent a SIGHUP. This means that someone who changes lusrlliblcrontab can get 
cron to look at it right away. 

You can also create the lusr/admlcronlog file, if you wish. If the file exists, cron logs to it each time it exe- 
cutes an instruction from lusrlliblcrontab. You can thus use the cronlog file to make sure cron is running 
properly. The lines in the file consist of a timestamp, and process statement Lines look something like 
this: 

Thu Mar 8 10:20:00 1984: /etc/dmesg - »/usr/adm/messages 
Thu Mar 8 10:29:59 1984: /etc/atrun 
Thu Mar 8 10:30:00 1984: /etc/dmesg - »/usr/adm/messages 
Thu Mar 8 10:39:59 1984: /etc/dmesg - »/usr/adm/messages 

FILES 

/usr/lib/crontab Instruction file 
/usr/adm/cronlog Log file 

SEE ALSO 

crontab(5) 
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NAME 

dcheck - file system directory consistency check 
SYNOPSIS 

/usr/etc/dcheck [ -i numbers ] [ filesystem ] 

DESCRIPTION 

N.B.: Dcheck is obsoleted for normal consistency checking by/sc&(8). 

Dcheck reads the directories in a file system and compares the link-count in each inode with the number of 
directory entries by which it is referenced. If the file system is not specified, dcheck checks a set of default 
file systems. 

Dcheck is fastest if the raw version of the special file is used, since the i-list is read in large chunks. 

OPTIONS 

— i numbers 

Numbers is a list of i-numbers; when one of those i-numbers turns up in a directory, the number, 
the i-number of the directory, and the name of the entry are reported. 

FILES 

Default file systems vary with installation. 

SEE ALSO 

fsck(8), icheck(8), fs(5), clri(8), ncheck(8) 

DIAGNOSTICS 

When a file turns up for which the link-count and the number of directory entries disagree, the relevant 
facts are reported. Allocated files which have 0 link-count and no entries are also listed. The only 
dangerous situation occurs when there are more entries than links; if entries are removed, so the link-count 
drops to 0, the remaining entries point to thin air. They should be removed. When there are more links 
than entries, or there is an allocated file with neither links nor entries, some disk space may be lost but the 
situation will not degenerate. 

BUGS 

Since dcheck is inherently two-pass in nature, extraneous diagnostics may be produced if applied to active 
file systems. 

Inode numbers less than 2 are invalid. 


Sun Release 3.0 


Last change: 4 February 1983 


509 



DIAG ( 8S ) 


MAINTENANCE COMMANDS 


DIAG ( 8S ) 


NAME 

diag - stand-alone disk initialization and diagnosis 

SYNOPSIS 

>b stand/diag 

DESCRIPTION 

Diag is a general purpose stand-alone package for initializing, diagnosing, and repairing disks. It supports 
the various SMD and ST-506 disk controllers. 

Note: Diag is not a system utility and can only be called from the Sun Workstation PROM monitor. 

The most common use of diag is formatting and labelling a disk — see the format, label, and partition 
commands. 

Immediately after startup, diag prompts for information about the particular disk drive(s) and controller(s) 
it is to work with. There is a facility for specifying additional information about nonstandard disks. 

Diag tries to access the disk controller you have defined. If tire attempt succeeds, it gives you a status 
report on the disk and issues the ‘diag>’ prompt. If the attempt fails (if the controller is ill-defined or 
nonexistent), you get a bus error message, and return to the PROM monitor. 

Once configured, diag accepts the comands listed below. Only enough characters to uniquely identify the 
command need be typed. 

abortdma Aborts/does not abort the dmatest command when a data miscompare is detected. That is, if 
the internal variable set by abortdma is ‘on’ (default), the dmatest command aborts as soon 
as it finds an error; otherwise, the dmatest continues. 

clear Sends a restore command to a disk. This is needed to manually reset disk faults. 

diag Re-initializes the diag program itself — goes back to phase one of the initialization process 

described above. 

dmatest Begins a continuous DMA test The test copies random data to and from the designated 
controller, comparing data. If a miscompare is found, an error message is displayed and the 
test aborts (unless the abortdma command is used — see abortdma, above). Note: this 
command is available only with the Xylogics 450 Controller. 

errors Reports/does not report all errors as they occur (toggles; default is reporting off). 

fix Formats and verifies a range of tracks; any defective tracks/sectors found are automatically 

corrected using mapping or slipping. Note: this command is available for SMD controllers 
only. 

format For SMD disks, formats the entire disk; for SCSI disks, initiates the SCSI format program, 
help or ? Displays a list of the available commands. 

info Reports/suppresses report of all disk activity as it completes (toggles; default is reporting 

off). 

label Labels the disk. 

map Displays current mappings and allows you to explicitly map one track/sector to a different 

track/sector. Usually used for manual bad sector mapping. The format and fix commands 
usually do this automatically when a bad track/sector is found. Note: the map command is 
disk controller-dependent: you can map tracks with an Interphase controller, and sectors 
with Xylogics controllers. This command is not available for use with Adaptec disk con- 
trollers (ST-506 interface). 

mapcheck Enables/disables checking for overlapping mapped sectors/tracks during the position, read, 
test, or write commands. If the internal variable set by mapcheck is ‘on’ when an error 
occurs (default), then the current mappings (if any) are read from the disk and checked to 
see if there are overlapping mappings over the area of the disk where the transfer failed. 
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partition 

position 

quit 

rhdr 

read 

scan 

seek 

slip 

slipmsgs 

status 

test 

time 

translate 

verify 

version 

whdr 

write 
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Creates, assigns, or modifies logical partition tables for a disk. The UNIX operating system 
requires logical partitions. The label command writes the partition map to the disk. There 
are standard partition tables for each type of disk that diag knows about. 

Continuously tests the disk by reading random sectors from the disk. To abort the test, type 
a'C (CONTROL-C). 

Quits from diag and returns to the PROM monitor. 

Reads and displays the track headers for a specified track. Note: this command is available 
for the Xylogics 450 controller only. 

Reads specified blocks from the disk. The read command prompts for the starting block 
number, number of blocks, and the block increment. The read command doesn’t report the 
data it reads — it is intended for verifying that blocks are readable. 

Continuously scans over a range of sectors looking for defective sectors by 
writing/reading/verifying various bit patterns to sequential sectors. Any data on the disk in 
the range to be scanned is destroyed. Sectors previously mapped are not scanned, so any 
errors reported will be newly found defective sectors. If used with a Xylogics controller, 
defective sectors can be automatically mapped/slipped when they are found. To abort the 
scan, type a “C (CONTROL-C). 

Performs a seek test on the disk: a seek is made to every cylinder and to every possible 
cylinder distance. 

Explicitly slips one sector on a track. Usually used for manual bad sector slipping. The for- 
mat and fix commands usually do this automatically when bad sectors are found and the 
proper conditions exist. Note: slipping is available only with the Xylogics 450 controller, 
and only when the disk has a spare data sector per track. 

Displays/suppresses display of track headers before and after each slip operation that occurs 
during the fix, format, and slip commands (toggles; default is display off). 

Reports the ready status of each drive on the current controller. 

Continuously tests the disk by writing random data to random sectors on the disk and then 
verifying that the correct data can be read back. The test command destroys data on the 
disk. To abort the test, type a A C (CONTROL-C). 

Turns timing on/off. When timing is on, diag reports on how long certain operations take — 
diag is less verbose in this state so it doesn’t waste time displaying messages (toggles; 
default is timing off). 

Translates a given block number into its decimal value, hexadecimal value, and logical disk 
address. 

Reads and displays the label from the disk. Shows the logical partition assignments. This 
done automatically when the label command has labelled the disk. 

Displays the SCCS identification strings for this version of diag. 

Modifies and writes the track headers for a specified track. Note: this command is avail- 
able with the Xylogics 450 controller only. Also, it should be used only for specialized 
patching — misuse may destroy track data. 

Verifies that blocks are writable by writing garbage data to specified blocks on the disk. 
The write command prompts for the starting block number, number of blocks, and the block 
increment. 

Adds two block numbers and reports the result in decimal, hexadecimal, and as a logical 
disk address. 

Subtracts two block numbers and reports the result in decimal, hexadecimal, and as a logical 
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disk address. 

Block numbers may be entered either as an absolute decimal block number, or as a disk address of the form 
cylinder/head/sector. 

Any diag command may be aborted by typing a "C (CONTROL-C). ‘ 
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NAME 

dkinfo - report information about a disk’s geometry and partitioning 
SYNOPSIS 

/etc/dkinfo disk[partition] 

DESCRIPTION 

Dkinfo gives the total number of cylinders, heads, and sectors or tracks on the specified disk, and gives this 
information along with the starting cylinder for the specified partition. If no partition is specified on the 
command line, dkinfo reports on all partitions. 

The disk specification here is a disk name of the form xxn, where xx is the controller device abbreviation 
(ip, xy, etc.) and n is the disk number. The partition specification is simply the letter used to identify that 
partition in the standard UNIX nomenclature. For example, ‘/etc/dkinfo xyO’ reports on the first disk in a 
system controlled by a Xylogics controller; ‘/etc/dkinfo xyOg’ reports on the seventh partition of such a 
disk. 

You must be be able to open /dev/rxxnp to run dkinfo. Usually, only the superuser can do so. 

EXAMPLE 

A request for information on my local disk, an 84 MByte disk controlled 
by a Xylogics 450 controller, might look like this: 

# /etc/dkinfo xyO 

xyO: Xylogics 450 controller at addr ee40, unit # 0 
586 cylinders 7 heads 32 sectors/track 
a: 15884 sectors (70 cyls, 6 tracks, 12 sectors) 
starting cylinder 0 
b: 33440 sectors (149 cyls, 2 tracks) 
starting cylinder 71 
c: 131264 sectors (586 cyls) 
starting cylinder 0 
d: No such device or address 
e: No such device or address 
f: No such device or address 
g: 81760 sectors (365 cyls) 
starting cylinder 221 
h: No such device or address 

# 

SEE ALSO 

dk(4), diag(8) 
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NAME 

dmesg - collect system diagnostic messages to form error log 
SYNOPSIS 

/usr/etc/dmesg [ - ] 

DESCRIPTION 

Dmesg looks in a system buffer for recently printed diagnostic messages and prints them on the standard 
output. The messages are those printed by the system when device (hardware) errors occur and (occasion- 
ally) when system tables overflow non-fatally. If the - flag is given, then dmesg computes (incrementally) 
the new messages since the last time it was run and places these on the standard output. This is typically 
used with cron{ 8) to produce the error log / usrladml messages by running the command 

/etc/dmesg - » /usr/adm/messages 
every 10 minutes. 

FILES 

/usr/adm/messages error log (conventional location) 

/usr/adm/msgbuf scratch file for memory of - option 

BUGS 

The system error message buffer is of small finite size. As dmesg is run only every few minutes, not all 
error messages are guaranteed to be logged. This can be construed as a blessing rather than a curse. 

Error diagnostics generated immediately before a system crash will never get logged. 
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NAME 

dump - incremental file system dump 
SYNOPSIS 

/etc/dump [ key [ argument . . . ] ] filesystem 
DESCRIPTION 

Dump copies to magnetic tape all files changed after a certain date in the filesystem. The key specifies the 
date and other options about the dump. Key consists of characters from the set 0-9|b|c| 

0-9 This number is the ‘dump level’. All files modified since the last date stored in the file 
/etc/dumpdates for the same filesystem at lesser levels will be dumped. If no date is determined by 
the level, the beginning of time is assumed; thus the entire filesystem is dumped if the 0 option is 
used. 

b Specifies the blocking factor for the dump. The blocking factor is taken from the next argument on 
the command line. The default blocking factor is 10. 

c Dump to cartridge tape instead of standard half-inch magnetic tape. 

d The density of the tape, expressed in BPI, is taken from the next argument. This is used in calculat- 
ing the amount of tape used per reel. The default is 1600. 

f Place the dump on the next argument file instead of the tape. If file is of the form machine .-device, 
dump to a remote machine. Since you normally run dump as root, the name of the remote machine 
must appear in the .r hosts file of the local machine. If argument is dump to standard output. If 
dump is called as rdump, the tape defaults to dumphost :ldevlrmt8, otherwise, the tape defaults to 
/dev/rmt8. Use an alias for dumphost in the file letclhosts to direct the output to a desired remote 
machine. 

n Whenever dump requires operator attention, notify by means similar to a wall( 1) all of the operators 
in the group “operator”. 

s The size of the dump tape is specified in feet. The number of feet is taken from the next argument. 
When the specified size is reached, dump waits for reels to be changed. The default tape size is 2300 
feet. 

u If the dump completes successfully, write the date of the beginning of the dump on file 
/ etc/dumpdates. This file records a separate date for each filesystem and each dump level. The for- 
mat of letc/dumpdates is readable by people, consisting of one free format record per line: filesystem 
name, increment level and ctime(3) format dump date, letc/dumpdates may be edited to change any 
of the fields, if necessary. 

w Dump tells the operator of filesystems which need to be dumped. The information is gleaned from 
the files letc/dumpdates and letclfstab . If the w option is set, all other options are ignored, and dump 
exits immediately. 

W Like the w, but the W option causes dump to print out, for each file system in letc/dumpdates the 
most recent dump date and level, and highlights those file systems that should be dumped. 

If no arguments are given, the key is assumed to be 9u. 

Dump requires operator intervention on these conditions: end of tape, end of dump, tape write error, tape 
open error or disk read error (if there are more than a threshold of 32). In addition to alerting all operators 
implied by the n key, dump interacts with the operator on dump's control terminal at times when dump can 
no longer proceed, or if something is grossly wrong. All questions dump poses must be answered by typ- 
ing “yes” or “no”, appropriately. 

Since making a dump involves a lot of time and effort for full dumps, dump checkpoints itself at the start of 
each tape volume. If writing that volume fails for some reason, dump will, with operator permission, res- 
tart itself from the checkpoint after the old tape has been rewound and removed, and a new tape has been 
mounted. 
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Dump tells the operator what is going on at periodic intervals, including usually low estimates of the 
number of blocks to write, the number of tapes it will take, the time to completion, and the time to the tape 
change. The output is verbose, so that others know that the terminal controlling dump is busy, and will be 
for some time. 

Now a short suggestion on how to perform dumps. Start with a full level 0 dump 
dump Oun 

Next, dumps of active file systems are taken on a daily basis, using a modified Tower of Hanoi algorithm, 
with this sequence of dump levels: 

3254769899... 

For the daily dumps, a set of 10 tapes per dumped file system is used on a cyclical basis. Each week, a 
level 1 dump is taken, and the daily Hanoi sequence repeats with 3. For weekly dumps, a set of 5 tapes per 
dumped file system is used, also on a cyclical basis. Each month, a level 0 dump is taken on a set of fresh 
tapes that is saved forever. 

FILES 

/dev/rmt8 default tape unit to dump to 
/etc/dumpdates new format dump date record 
/etc/fstab dump table: file systems and frequency 
/etc/group to find group operator 

SEE ALSO 

restore(8), dump(5), fstab(5) 

DIAGNOSTICS 

Many, and verbose. 

Dump exit codes worthy of note are: 

0 normal exit when w or W options are used. 

1 normal exit 

2 error - restart writing from last checkpoint 

3 abort - no checkpoint attempted. 

BUGS 

Sizes are based on 1600 BPI blocked tape; the raw magtape device has to be used to approach these densi- 
ties. Fewer than 32 read errors on the filesystem are ignored. Each reel requires a new process, so parent 
processes for reels already written just hang around until the entire tape is written. 

It would be nice if dump knew about the dump sequence, kept track of the tapes scribbled on, told the 
operator which tape to mount when, and provided more assistance for the operator running restore. 
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NAME 

dumpfs - dump file system information 
SYNOPSIS 

/usr/etc/dumpfs device 
DESCRIPTION 

Dumpfs prints out the super block and cylinder group information for the file system or special device 
specified. The listing is very long and detailed. This command is useful mostly for finding out certain file 
system information such as the file system block size and minimum free space percentage. 

SEE ALSO 

fs(5), tunefs(8), newfs(8), fsck(8) 
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NAME 

edquota - edit user quotas 
SYNOPSIS 

/usr/etc/edquota [ — p proto-user ] users... 

/usr/etc/edquota -t 

DESCRIPTION 

Edquota is a quota editor. One or more users may be specified on the command line. For each user a tem- 
porary file is created with an ASCII representation of the current disk quotas for that user and an editor is 
then invoked on the file. The quotas may then be modified, new quotas added, etc. Upon leaving the edi- 
tor, edquota reads the temporary file and modifies the binary quota files to reflect the changes made. 

If the -p option is specified, edquota will duplicate the quotas of the prototypical user specified for each 
user specified. This is the normal mechanism used to initialize quotas for groups of users. 

The -t option edits the soft time limits for each file system. If the time limits are zero, the default time lim- 
its in <ufslquota.h> are used. Time units of sec(onds), min(utes), hour(s), day(s), week(s), and month(s) 
are understood. Time limits are printed in the greatest possible time unit such that the value is greater than 
or equal to one. 

The editor invoked is vi(l) unless the environment variable EDITOR specifies otherwise. 

Only the super-user may edit quotas. 

FILES 

quotas quota file at the file system root 

/ etc/ mtab mounted file systems 

SEE ALSO 

quota(l), quotactl(2), quotacheck(8), quotaon(8), repquota(8) 

BUGS 

The format of the temporary file is inscrutable. 
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NAME 

etherd - ethemet statistics server 
SYNOPSIS 

/usr/etc/rpc.etherd interface 
DESCRIPTION 

Etherd is a server which puts interface into promiscuous mode, and keeps summary statistics of all the 
packets received on that interface. It responds to rpc requests for the summary. Traffic(l) displays the 
information obtained from etherd in graphical form. 

SEE ALSO 

traffic(l) 
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NAME 

etherfind - find packets on ethemet 
SYNOPSIS 

etherfind [ -n ] [ -x ] [ -c count ] [ -i interface ] [ -p ] expression 
DESCRIPTION 

Etherfind prints out the headers of packets on the ethemet that match the boolean expression. When an 
internet packet is fragmented into more than one ethemet packet, all fragments except the first are marked 
with an asterisk. You must be root to invoke etherfind. 

OPTIONS 

-n Don’t convert host addresses and port numbers to names. 

-x Dump the header in hex, in addition to the line printed for each packet by default 

-c Exit after receiving count packets. This is sometimes useful for dumping a sample of ethemet 

traffic to a file for later analysis. 

-i Etherfind listens on interface. The default is ieO. The program netstat(8) when invoked with the 
•i flag lists all the interfaces that a machine has. 

-p Normally, the selected interface is put into promiscuous mode, so that etherfind has access to all 

packets on the ethemet. However, when the -p flag is used, the interface will not go promiscuous. 

expression 

The syntax of of expression is similar to that used by find(l). Here are the allowable primaries. 

— dst destination 

True if the destination field of the packet is destination, which may be either an address 
or a name. 

— src source 

True if the source field of the packet is source, which may be either an address or a name, 
-between hostl host2 

True if either the source of the packet is hostl and the destination hostl, or the source is 
host2 and the destination hostl. 

-dstnet destination 

True if the destination field of the packet has a network part of destination, which may be 
either an address or a name. 

— srcnet source 

True if the source field of the packet has a network part of source, which may be either 
an address or a name. 

-srcport port 

True if the packet has a source port value of port. It must be either upd or tcp (see 
tcp{4V)),udp(4V)). The port can be a number or a name used in /etc/services. 

-dstport port 

True if the packet has a destination port value of port. The port can be a number or a 
name. 

-less length 

True if the packet has a length less than or equal to length. 

-greater length 

True if the packet has a length greater than or equal to length. 

-proto protocol 

True if the packet is an ip packet (see ip (,4V)) of protocol type protocol. Protocol can be 
a number or one of the names icmp, udp, nd, or tcp. 
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-byte byte op value 

True if byte number byte of the packet is in relation op to value. Legal values for op are 
+, <, >, &, and |. Thus 4=6 is true if the fourth byte of the packet has the value 6, and 
20&0xf is true if byte twenty has one of its fbur low order bits nonzero. 

-broadcast 

True if the packet is a broadcast packet. 

-arp True if the packet is a arp packet (see arpiA'P)). 

-rarp True if the packet is a rarp packet. 

-ip True if the packet is an ip packet 

The primaries may be combined using the following operators (in order of decreasing precedence): 

A parenthesized group of primaries and operators (parentheses are special to the Shell and must be 
escaped). 

The negation of a primary ('!’ is the unary not operator). 

Concatenation of primaries (the and operation is implied by the juxtaposition of two primaries). 
Alternation of primaries (‘-o’ is the or operator). 

EXAMPLE 

To find all packets arriving at or departing from sundown 

angel% etherfind -src sundown -o -dst sundown 
angel% 

Note that the { } characters must be quoted when using the C shell. 

SEE ALSO 

traffic(l), nit(4p) 

BUGS 

The syntax is painful. 
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NAME 

expire - remove outdated news articles 
SYNOPSIS 

/usr/Iib/news/expire [ -n newsgroups ] [ — i ] [ — I ] [ —\[level ] ] [ -e days ] [ -a ] 

[ — r ] [ — h ] 

DESCRIPTION 

Expire is normally started up by cron{ 8) every night to remove all expired news. If no newsgroups are 
specified, the default is to expire all. 

Articles whose specified expiration date has already passed are considered expirable. 

OPTIONS 

— n newsgroups 

List of newsgroups to expire. Elements in the list of newsgroups must be separated by commas 
and/or spaces. 

-a archive articles in /usr/spool/oldnews. Articles are unlinked in the absence of the -a option. 
—\[level] 

be more verbose. A verbosity level (default 1) can follow the -v flag, as in -v3 for even more 
output. This is useful if articles aren’t being expired and you want to know why. 

— e days 

give the number of days to use for a default expiration date. If not given, an installation depen- 
dent default (often 2 weeks) is used. Note that you must use a space between -e and days. 

-i 

-I ignore any expiration date explicitly given on articles. This can be used when disk space is really 
tight. -I always ignores expiration dates, while -i only ignores the date if ignoring it would 
expire the article sooner. WARNING: If you have articles archived by giving them expiration 
dates far into the future, these options might remove these files anyway. 

-r rebuild the history file without removing any files. In the process, expire formats the dbm{ 3) for- 
mat files associated with the history file. 

-h expire articles without using the history file. Both the -r and -h flags use the active file for news- 
group information rather than the history file. 

SEE ALSO 

checknews(l), inews(l), readnews(l), recnews(8), sendnews(8), uurec(8) 
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NAME 

fastboot, fasthalt - reboot/halt the system without checking the disks 
SYNOPSIS 

/etc/fastboot [ boot-options ] 

/etc/fasthalt [ halt-options ] 

DESCRIPTION 

Fastboot and fasthalt are shell scripts which reboot and halt the system without checking the file systems. 
This is done by creating a file / 'fastboot , then invoking the reboot program. The system startup script, 
letclrc, looks for this file and, if present, skips the normal invocation of fsck(S). 

SEE ALSO 

halt(8), reboot(8), rc(8) 


Sun Release 3.0 


Last change: 4 March 1983 


523 



FSCK ( 8 ) 


MAINTENANCE COMMANDS 


FSCK ( 8 ) 


NAME 

fsck - file system consistency check and interactive repair 
SYNOPSIS 

/etc/fsck -p [ filesystem ... ] 

/etc/fsck [ -b block# ] [ -y ] [ -n ] [ filesystem ] ... 

DESCRIPTION 

The first form of fsck preens a standard set of filesystems or the specified file systems. It is normally used 
in the script /etc/rc during automatic reboot. In this case fsck reads the table /etc/fstab to determine which 
file systems to check. It uses the information there to inspect groups of disks in parallel taking maximum 
advantage of i/o overlap to check the file systems as quickly as possible. Normally, the root file system 
will be checked on pass 1, other “root” (“a” partition) file systems on pass 2, other small file systems on 
separate passes (e.g. the “d” file systems on pass 3 and the “e” file systems on pass 4), and finally the 
large user file systems on the last pass, e.g. pass 5. A pass number of 0 in fstab causes a disk to not be 
checked; similarly partitions which are not shown as to be mounted “rw” or “ro” are not checked. 

The system takes care that only a restricted class of innocuous inconsistencies can happen unless hardware 
or software failures intervene. These are limited to the following: 

Unreferenced inodes 

Link counts in inodes too large 

Missing blocks in the free list 

Blocks in the free list also in files 

Counts in the super-block wrong 

These are the only inconsistencies which fsck with the -p option will correct; if it encounters other incon- 
sistencies, it exits with an abnormal return status and an automatic reboot will then fail. For each corrected 
inconsistency one or more lines will be printed identifying the file system on which the correction will take 
place, and the nature of the correction. After successfully correcting a file system, fsck will print the 
number of files on that file system and the number of used and free blocks. 

Without the -p option, fsck audits and interactively repairs inconsistent conditions for file systems. If the 
file system is inconsistent the operator is prompted for concurrence before each correction is attempted. It 
should be noted that a number of the corrective actions which are not fixable under the -p option will result 
in some loss of data. The amount and severity of data lost may be determined from the diagnostic output. 
The default action for each consistency correction is to wait for the operator to respond yes or no. If the 
operator does not have write permission fsck will default to a -n action. 

Fsck has more consistency checks than its predecessors check, dcheck, f check, and icheck combined. 

The following flags are interpreted by fsck. 

-b Use the block specified immediately after the flag as the super block for the file system. Block 32 is 
always an alternate super block. 

-y Assume a yes response to all questions asked by fsck; this should be used with great caution as this 
is a free license to continue after essentially unlimited trouble has been encountered. 

-n Assume a no response to all questions asked by fsck; do not open the file system for writing. 

If no filesystems are given to fsck then a default list of file systems is read from the file /etc/fstab. 
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Inconsistencies checked are as follows: 

1. Blocks claimed by more than one inode or the free list. 

2. Blocks claimed by an inode or the free list outside the range of the file system. 

3. Incorrect link counts. 

4. Size checks: 

Directory size not of proper format. 

5. Bad inode format. 

6. Blocks not accounted for anywhere. 

7. Directory checks: 

File pointing to unallocated inode. 

Inode number out of range. 

8. Super Block checks: 

More blocks for inodes than there are in the file system. 

9. Bad free block list format. 

10. Total free block and/or free inode count incorrect. 

Orphaned files and directories (allocated but unreferenced) are, with the operator’s concurrence, recon- 
nected by placing them in the lost+found directory. The name assigned is the inode number. The only res- 
triction is that the directory lost+found must preexist in the root of the filesystem being checked and must 
have empty slots in which entries can be made. This is accomplished by making lost+found, copying a 
number of files to the directory, and then removing them (before fsck is executed). 

Checking the raw device is almost always faster. 

FILES 

/etc/fstab contains default list of file systems to check. 

DIAGNOSTICS 

The diagnostics produced by fsck are intended to be self-explanatory. 

SEE ALSO 

fstab(5), fs(5), newfs(8), mkfs(8), crash(8S), reboot(8) 

BUGS 

Inode numbers for . and .. in each directory should be checked for validity. 

There should be some way to start a fsck -p at pass n. 
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NAME 

fsirand - install random inode generation numbers 

SYNOPSIS 

fsirand [ -p ] special 

DESCRIPTION 

Fsirand installs random inode generation numbers on all the inodes on device special, and also installs a 
filesystem ID in the superblock. This helps increase the security of filesystems exported by NFS. 

Fsirand must be used only on an unmounted filesystem that has been checked with fsck{ 8). The only 
exception is that it can be used on the root filesystem in single-user mode, if the system is immediately re- 
booted afterwords. 

OPTIONS 

-p Print out the generation numbers for all the inodes, but do not change the generation numbers. 
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NAME 

ftpd - DARPA Internet File Transfer Protocol server 
SYNOPSIS 

/usr/etc/in.ftpd host.socket 
DESCRIPTION 

Ftpd is the DARPA Internet File Transfer Prototocol server process. The server is invoked by the Internet 
daemon inetd{ 8C) each time a connection to the ftp service (see services (5)) is made, with the connection 
available as descriptor 0 and the host and socket the connection originated from (in hex and decimal 
respectively) as argument. 

Inactive connections are timed out after 60 seconds. 

The ftp server currently supports the following ftp requests; case is not distinguished. 


Request 

Description 

ACCT 

specify account (ignored) 

ALLO 

allocate storage (vacuously) 

APPE 

append to a file 

CWD 

change working directory 

DELE 

delete a file 

HELP 

give help information 

LIST 

give list files in a directory (“Is -lg”) 

MODE 

specify data transfer mode 

NLST 

give name list of files in directory (“Is”) 

NOOP 

do nothing 

PASS 

specify password 

PORT 

specify data connection port 

QUIT 

terminate session 

RETR 

retrieve a file 

RNFR 

specify rename-from file name 

RNTO 

specify rename-to file name 

STOR 

store a file 

STRU 

specify data transfer structure 

TYPE 

specify data transfer type 

USER 

specify user name 

XCUP 

change to parent of current working directory 

XCWD 

change working directory 

XMKD 

make a directory 

XPWD 

print the current working directory 

XRMD 

remove a directory 


The remaining ftp requests specified in Internet RFC 765 are recognized, but not implemented. 

Ftpd interprets file names according to the “globbing” conventions used by c$A(l). This allows users to 

utilize the metacharacters “*?□{}'”. 

Ftpd authenticates users according to three rules. 

1) The user name must be in the password data base, letclpasswd, and not have a null password. In 
this case a password must be provided by the client before any file operations may be performed. 

2) The user name must not appear in the file lusr/etc/ftpusers. 

3) If the user name is “anonymous” or “ftp”, an anonymous ftp account must be present in the 
password file (user “ftp”). In this case the user is allowed to log in by specifying any password 
(by convention this is given as the client host’s name). 
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In the last cas e,ftpd takes special measures to restrict the client’s access privileges. The server performs a 
chroot(2) command to the home directory of the “ftp” user. In order that system security is not breached, 
it is recommended that the “ftp” subtree be constructed with care; the following rules are recommended. 

"ftp Make the home directory owned by ‘ ‘ftp’ ’ and unwritable by anyone. 

"ftp/bin Make this directory owned by the super-user and unwritable by anyone. The program /s(l) must 
be present to support the list commands. This program should have mode 111. 

"ftp/etc Make this directory owned by the super-user and unwritable by anyone. The files passwd{5) and 
group (5) must be present for the Is command to work properly. These files should be mode 444. 

"ftp/pub Make this directory mode 111 and owned by “ftp”. Users should then place files which are to 
be accessible via the anonymous account in this directory. 

SEE ALSO 

ftp(lC), ftpusers(5) 

BUGS 

There is no support for aborting commands. 

The anonymous account is inherently dangerous and should avoided when possible. 

The server must run as the super-user to create sockets with privileged port numbers. It maintains an effec- 
tive user id of the logged in user, reverting to the super-user only when binding addresses to sockets. The 
possible security holes have been extensively scrutinized, but are possibly incomplete. 
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NAME 

gettable - get NIC format host tables from a host 

SYNOPSIS 

/etc/gettable host 

DESCRIPTION 

Gettable is a simple program used to obtain the NIC standard host tables from a “nicname” server. The 
indicated host is queried for the tables. The tables, if retrieved, are placed in the file hosts.txt. 

Gettable operates by opening a TCP connection to the port indicated in the service specification for “nic- 
name”. A request is then made for “ALL” names and the resultant information is placed in the output 
file. 

Gettable is best used in conjunction with the htable($) program which converts the NIC standard file for- 
mat to that used by the network library lookup routines. 

SEE ALSO 

intro(3N), htable(8) 

BUGS 

Should allow requests for only part of the database. 
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NAME 

getty - set terminal mode 

SYNOPSIS 

/etc/getty [ char ] 

DESCRIPTION 

Getty is invoked by init( 8) immediately after a terminal is opened, following the making of a connection. 
While reading the name getty attempts to adapt the system to the speed and type of terminal being used. 

I nit calls getty with an argument specified by the ttys file entry for the terminal line. Arguments other than 
‘0’ can be used to make getty treat the line specially. Refer to ttys(5) and gettytab(5) for descriptions of 
how getty uses the data in gettytab to set up the terminal. Normally, it sets the speed of the interface to 300 
baud, specifies that raw mode is to be used (break on every character), that echo is to be suppressed, and 
either parity allowed. It types a banner identifying the system (from gethostname(2» and the ‘login:’ mes- 
sage. Then the user’s name is read, a character at a time. If a null character is received, it is assumed to be 
the result of the user pushing the ‘break’ (‘interrupt’) key. The speed is then changed to 1200 baud and the 
‘login:’ is typed again; a second ‘break’ changes the speed to 150 baud and the ‘login:’ is typed again. 
Successive ‘break’ characters cycle through the speeds 300, 1200, and 150 baud. 

The user’s name is terminated by a new-line or carriage-return character. The latter results in the system 
being set to treat carriage returns appropriately (see rry(4)). 

The user’s name is scanned to see if it contains any lower-case alphabetic characters; if not, and if the 
name is nonempty, the system is told to map any future upper-case characters into the corresponding 
lower-case characters. 

Finally, login is called with the user’s name as argument. 

SEE ALSO 

init(8), login(l), ioctl(2), tty(4), ttys(5), getty tab(5) 
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NAME 

gpconfig - initialize the Graphics Processor 
SYOPNSIS 

/usr/etc/gpconfig gpunit [ [-b] [-f \fbunit ... ] 

DESCRIPTION 

gpconfig binds cgtwo frame buffers to the Graphics Processor (GP), and loads and starts the appropriate 
microcode in the GP. For example, the command line: 

/usr/etc/gpconfig gponeO cgtwoO cgtwol 

will bind the frame buffer boards cgtwoO and cgtwol to the Graphics Processor gponeO . The devices 
Idev/gponeOa and /dev/gponeOb will then refer to the combination of gpone and cgtwoO or cgtwol respec- 
tively. 

The same cgtwo frame buffer cannot be bound to more than one GP. 

All cgtwo frame buffer boards bound to a GP must be configured to the same width and height. 

Note: The standard version of the file letclrc.local contains the following gpconfig command line: 
/usr/etc/gpconfig gponeO -f -b cgtwoO 

This binds gponeO and cgtwoO as gponeOa, causes gponeOa to use the Graphics Buffer Board if it is 
present, and redirects Idevlfb to be Idevl gponeOa . If another configuration is desired, edit the command line 
in letclrc.local to do the appropriate thing. 

Note: It is inadvisable to run the gpconfig command while the GP is being used. Unpredictable results may 
occur. If it is neccessary to change the frame buffer bindings to the GP (or to stop using the GP alto- 
gether), bring the system down gently, boot single user, edit the gpconfig line in the letclrc.local file, and 
bring the system back up multiuser. 

OPTIONS 

-b Configure the GP to use the Graphics Buffer as well. Note: Currently only one GP / frame buffer 
binding is allowed to use the graphics buffer at a time. Only the last -b option in the command 
line takes effect. 

-f Indicates that the next frame buffer specified is to be used for Idevlfb as well. Only the last -f 
option in the command line takes effect. 

FILES 

/dev/cgtwo[0-9] 

/dev/fb 

/dev/gpone[0-3] [abed] 

/usr/lib/gplcg2. 1024.ucode 
/usr/lib/gplcg2. 1 152.ucode 
/etc/rc.local 

SEE ALSO 

cgtwo(4S), gpone(4S) 
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NAME 

gxtest - stand alone test for the Sun video graphics board 

SYNOPSIS 

b /stand/gxtest 

DESCRIPTON 

Gxtest runs stand alone, not under control of the UNIX operating system. With the PROM resident moni- 
tor in control of the system, type the command: 

> b /stand/gxtest 

and the monitor boots the video test program into memory. Gxtest is completely self-explanatory and runs 
under its own steam. It reports any errors it finds on the screen. 
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NAME 

halt - stop the processor 
SYNOPSIS 

/etc/halt [ -n ] [ -q ] [ -y ] 

DESCRIPTION 

Halt writes out sandbagged information to the disks and then stops the processor. 
OPTIONS 

-n Prevents the sync before stopping. 

-q Do a quick halt, no graceful shutdown is attempted. 

-y Needed if you are trying to halt the system from a dialup. 

SEE ALSO 

reboot(8), shutdown(8) 
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NAME 

htable - convert NIC standard format host tables 

SYNOPSIS 

/usr/etc/htable file 

DESCRIPTION 

Htable is used to convert host files in the format specified in Internet RFC 810 to the format used by the 
network library routines. Three files are created as a result of running htable : hosts, networks, and gate- 
ways. The hosts file is used by the gethostent(3N) routines in mapping host names to addresses. The net- 
works file is used by the getnetent(3N) routines in mapping network names to numbers. The gateways file 
is used by the routing daemon in identifying “passive” Internet gateways; see routed^ 8C) for an explana- 
tion. 

If any of the files localhosts, localnetworks , or localgateways are present in the current directory, the file’s 
contents is prepended to the output file without interpretation. This allows sites to maintain local aliases 
and entries which are not normally present in the master database. 

Htable is best used in, conjunction with the ge t table (&C) program which retrieves the NIC database from a 
host. 

SEE ALSO 

intro(3N), gettable(8C) 

BUGS 

Does not properly calculate the gateways file. 
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NAME 

icheck - file system storage consistency check 
SYNOPSIS 

/usr/etc/icheck [ -s ] [ -b numbers ] [ filesystem ] 

DESCRIPTION 

N.B.: Icheck is obsoleted for normal consistency checking by/rcfc(8). 

Icheck examines a file system, builds a bit map of used blocks, and compares this bit map against the free 
list maintained on the file system. If the file system is not specified, a set of default file systems is checked. 
The normal output of icheck includes a report of 

The total number of files and the numbers of regular, directory, block special and character special 
files. 

The total number of blocks in use and the numbers of single-, double-, and triple-indirect blocks 
and directory blocks. 

The number of free blocks. 

The number of blocks missing; i.e. not in any file nor in the free list. 

The -s option causes icheck to ignore the actual free list and reconstruct a new one by rewriting the super- 
block of the file system. The file system should be dismounted while this is done; if this is not possible (for 
example if the root file system has to be salvaged) care should be taken that the system is quiescent and that 
it is rebooted immediately afterwards so that the old, bad in-core copy of the super-block will not continue 
to be used. Notice also that the words in the super-block which indicate the size of the free list and of the 
i-list are believed. If the super-block has been curdled these words will have to be patched. The -s option 
causes the normal output reports to be suppressed. 

Following the -b option is a list of block numbers; whenever any of the named blocks turns up in a file, a 
diagnostic is produced. 

Icheck is faster if the raw version of the special file is used, since it reads the i-list many blocks at a time. 

FILES 

Default file systems vary with installation. 

SEE ALSO 

fsck(8), dcheck(8), ncheck(8), fs(5), clri(8) 

DIAGNOSTICS 

For duplicate blocks and bad blocks (which lie outside the file system) icheck announces the difficulty, the 
i-number, and the kind of block involved. If a read error is encountered, the block number of the bad block 
is printed and icheck considers it to contain 0. ‘Bad freeblock’ means that a block number outside the 
available space was encountered in the free list, ‘n dups in free’ means that n blocks were found in the free 
list which duplicate blocks either in some file or in the earlier part of the free list 

BUGS 

Since icheck is inherently two-pass in nature, extraneous diagnostics may be produced if applied to active 
file systems. 

It believes even preposterous super-blocks and consequently can get core images. 

The system should be fixed so that the reboot after fixing the root file system is not necessary. 
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NAME 

ifconfig - configure network interface parameters 
SYOPNSIS 

/etc/ifconfig interface [ Ethernet _addr ess ] [ hostname ] [ parameters ] 

DESCRIPTION 

Ifconfig is used to assign an address to a network interface and/or to configure network interface parame- 
ters. Ifconfig must be used at boot time to define the network address of each interface present on a 
machine; it may also be used at a later time to redefine an interface’s address. Used without options, 
ifconfig displays the current configuration for a network interface. Only the super-user may modify the 
configuration of a network interface. 

The interface parameter is a string of the form “name unit”, for example “ieO”. 

OPTIONS 

Ethernet _address is the hardware Ethernet address of a given machine. The address is a 6-byte hexade- 
cimal value; each byte of the address is separated by a colon. A typical Ethernet adddress is 
‘8:0:20:1:1:A3’. This address is contained in the ID PROM on the Sun-2 CPU Board, and is reported at 
boot time as one of the PROM monitor’s sign-on messages. The Ethernet address option is normally not 
used — the hardware supplies the default; the option is used only when trying to talk to a device which 
does not support ARP (like a VAX on a 4.1c network). 

hostname may be either the hostname of a given machine (present in the hostname database, hosts(5)), or 
the complete Internet address consisting of your system’s network number and the machine’s unique host 
number. A typical Internet address might be “192.9.200.44”, where “192.9.200” is the network number 
and “44” is the machine’s hostnumber. To find a machine’s Internet address, consult the local letclhosts 
file. 

The following parameters may be set with ifconfig: 
up Mark an interface “up”. 

down Mark an interface “down”. When an interface is marked “down”, the system will not 

attempt to transmit messages through that interface. 

trailers Enable the use of a “trailer” link level encapsulation when sending (default). If a net- 

work interface supports trailers, the system will, when possible, encapsulate outgoing 
messages in a manner which minimizes the number of memory to memory copy opera- 
tions performed by the receiver. 

-trailers Disable the use of a “trailer” link level encapsulation. 

arp Enable the use of the Address Resolution Protocol in mapping between network level 

addresses and link level addresses (default). This is currently implemented for mapping 
between DARPA Internet addreses and lOMb/s Ethernet addresses. 

-arp Disable the use of the Address Resolution Protocol. 

DIAGNOSTICS 

Messages indicating the specified interface does not exit, the requested address is unknown, the user is not 
privileged and tried to alter an interface’s configuration. 

SEE ALSO 

rc(8), intro(4N), netstat(l) 
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NAME 

imemtest - stand alone memory test 
SYNOPSIS 

b /stand/imemtest 
DESCRIPTON 

Imemtest runs stand alone, not under control of the UNIX operating system. With the PROM resident 
monitor in control of the system, type the command: 

> b /stand/imemtest 

and the monitor boots the memory test program into memory. Imemtest is completely self-explanatory. It 
prompts for all start and end addresses, and after that it runs under its own steam. It reports any errors it 
finds on the screen. 
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NAME 

inetd - internet services daemon 

SYNOPSIS 

/etc/inetd [ -d ] 

DESCRIPTION 

Inetd is the internet super-server which invokes all internet server processes as needed. Connection- 
oriented services are invoked each time a connection is made, by creating a process. This process is passed 
the connection as file descriptor 0 and an argument of the form “sourcehost.sourceport” where sourcehost 
is hex and sourceport is decimal. 

Datagram oriented services are invoked when a datagram arrives; a process is created and passed the con- 
nection as file descriptor 0. Inetd will look at the socket where datagrams arrive again only after this pro- 
cess completes. The paradigms for such proceses are either to read off the incoming datagram and then 
fork and exit, or to process the arriving datagram and then time out 

Inetd consults servers (5) when it is invoked, and supports whatever services are in that file. 

An rpc server can be started from inetd. The only differences from the usual code are that svcudp_create 
should be called as: 

transp = scvudpcreate(O) 

since inet passes a socket file as descriptor 0, and svc register should be called as: 

svc_register(PROGNUM, VERSNUM, service, transp, 0) 

with the final flag as 0, since the program will already have been registered by inetd. If you want to exit 
from the server process and return control to inet, you must explicitly exit since scv_run never returns. 

The format of entries in / etc/ servers for rpc services is: 

rpc udp server-program program-number version-number 

where server-program is the C code implementing the server, and program-number, version-number are 
the program, and version numbers, respectively of the service. The keyword udp can be replaced by tcp 
for tcp -based services. 

If the same program handles multiple versions, the version number can be specified as a range: 
rpc udp /usr/etc/rstatd 100001 1-2 

OPTIONS 

-d Specifies that debugging traces are to be turned on for connection-oriented (TCP) services. 

FILES 

/etc/servers list of internet server processes 
SEE ALSO 

servers(5), comsat(8C), ftpd(8C), rexecd(8C), rlogind(8C), syslog(8), rshd(8C), talkd(8C), telnetd(8C), 
tftpd(8C) 

BUGS 

There is no provision for selectively invoking TCP debugging packet tracing per-service. 

Should reread the letc/servers file on receipt of a SIGHUP signal. The /etc/servers file can have no more 
than 26 lines. 
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NAME 

init — process control initialization 
SYNOPSIS 

/etc/init 

DESCRIPTION 

Init is invoked inside UNIX as the last step in the boot procedure. It normally then runs the automatic 
reboot sequence as described in reboot l 8), and if this succeeds, begins multi-user operation. If the reboot 
fails, it commences single user operation by giving the super-user a shell on the console. It is possible to 
pass parameters from the boot program to init so that single user operation is commenced immediately. 
When such single user operation is terminated by killing the single-user shell (i.e. by hitting A D), init runs 
letclrc without the reboot parameter. This command file performs housekeeping operations such as remov- 
ing temporary files, mounting file systems, and starting daemons. 

In multi-user operation, init’ s role is to create a process for each terminal port on which a user may log in. 
To begin such operations, it reads the file letclttys and forks several times to create a process for each ter- 
minal specified in the file. Each of these processes opens the appropriate terminal for reading and writing. 
These channels thus receive file descriptors 0, 1 and 2, the standard input and output and the diagnostic out- 
put. Opening the terminal will usually involve a delay, since the open is not completed until someone is 
dialed up and earner established on the channel. If a terminal exists but an error occurs when trying to 
open the terminal init complains by writing a message to the system console; the message is repeated every 
10 minutes for each such terminal until the terminal is shut off in /etc/ttys and init notified (by a hangup, as 
described below), or the terminal becomes accessible (init checks again every minute). After an open 
succeeds, letclgetty is called with argument as specified by the second character of the ttys file line. Getty 
reads the user’s name and invokes login to log in the user and execute the Shell. 

Ultimately the Shell will terminate because of an end-of-file either typed explicitly or generated as a result 
of hanging up. The main path of init, which has been waiting for such an event, wakes up and removes the 
appropriate entry from the file utmp, which records current users, and makes an entry in /usr/adm/wtmp, 
which maintains a history of logins and logouts. The wtmp entry is made only if a user logged in success- 
fully on the line. Then the appropriate terminal is reopened and getty is reinvoked. 

Init catches the hangup signal (signal SIGHUP) and interprets it to mean that the file letclttys should be 
read again. The Shell process on each line which used to be active in ttys but is no longer there is ter- 
minated; a new process is created for each added line; lines unchanged in the file are undisturbed. Thus it 
is possible to drop or add phone lines without rebooting the system by changing the ttys file and sending a 
hangup signal to the init process: use ‘kill -HUP 1.’ 

Init will terminate multi-user operations and resume single-user mode if sent a terminate (TERM) signal, 
i.e. “kill -TERM 1”. If there are processes outstanding which are deadlocked (due to hardware or 
software failure), init will not wait for them all to die (which might take forever), but will time out after 30 
seconds and print a warning message. 

Init will cease creating new getty ’s and allow the system to slowly die away, if it is sent a terminal stop 
(TSTP) signal, i.e. “kill -TSTP 1”. A later hangup will resume full multi-user operations, or a terminate 
will initiate a single user shell. This hook is used by reboot (8) and halt (8). 

Init’ s role is so critical that if it dies, the system will reboot itself automatically. If, at bootstrap time, the 
init process cannot be located, the system will loop in user mode at location 0x13. 

DIAGNOSTICS 

init: tty : cannot open. A terminal which is turned on in the rc file cannot be opened, likely because the 
requisite lines are either not configured into the system or the associated device was not attached during 
boot-time system configuration. 

WARNING: Something is hung (wont die); ps axl advised. A process is hung and could not be killed 
when the system was shutting down. This is usually caused by a process which is stuck in a device driver 
due to a persistent device error condition. 
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FILES 

/dev/console, /dev/tty*, /etc/utmp, /usr/adnVwtmp, /etc/ttys, /etc/rc 
SEE ALSO 

login(l), kill(l), sh(l), ttys(5), getty(8), rc(8), reboot(8), halt(8), shutdown(8) 
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NAME 

iostat - report I/O statistics 
SYNOPSIS 

iostat [ interval [ count ] ] 

DESCRIPTION 

Iostat iteratively reports the number of characters read and written to terminals, and, for each disk, the 
number of seeks and transfers per second, and the milliseconds per average seek. It also gives the percen- 
tage of time the system has spent in user mode, in user mode running low priority (niced) processes, in sys- 
tem mode, and idling. 

To compute this information, for each disk, seeks and data transfer completions and number of words 
transferred are counted; for terminals collectively, the number of input and output characters are counted. 
Also, each fiftieth of a second, the state of each disk is examined and a tally is made if the disk is active. 
From these numbers and given the transfer rates of the devices it is possible to determine average seek 
times for each device. 

The optional interval argument causes iostat to report once each interval seconds. The first report is for all 
time since a reboot and each subsequent report is for the last interval only. 

The optional count argument restricts the number of reports. 

FILES 

/dev/kmem 

/vmunix 

SEE ALSO 

vmstat(8) 
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NAME 

kgmon - generate a dump of the operating system’s profile buffers 
SYNOPSIS 

/usr/etc/kgmon [ -b ] [ -h ] [ -r ] [ -p ] [ system ] [ memory ] 

DESCRIPTION 

Kgmon is a tool used when profiling the operating system. When no arguments are supplied, kgmon indi- 
cates the state of operating system profiling as running, off, or not configured (see config(8)). If the -p flag 
is specified, kgmon extracts profile data from the operating system and produces a gmon.out file suitable for 
later analysis by gprof( 1). 

OPTIONS 

-b Resume the collection of profile data. 

-h Stop the collection of profile data. 

-p Dump the contents of the profile buffers into a gmon.out file. 

-r Reset all the profile buffers. If the -p flag is also specified, the gmon.out file is generated before 
the buffers are reset. 

If neither -b nor -h is specified, the state of profiling collection remains unchanged. For example, if the 
-p flag is specified and profile data is being collected, profiling is momentarily suspended, the operating 
system profile buffers are dumped, and profiling is immediately resumed. 

FILES 

/vmunix - the default system 
/dev/kmem - the default memory 

SEE ALSO 

gprof (1), config(8) 

DIAGNOSTICS 

Users with only read permission on /dev/kmem cannot change the state of profiling collection. They can 
get a gmon.out file with the warning that the data may be inconsistent if profiling is in progress. 
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NAME 

lpc - line printer control program 
SYNOPSIS 

/usr/etc/lpc [ command [ command-parameter ... ] ] 

DESCRIPTION 

Lpc is the Line Printer Control program and is used by the system administrator to control the operation of 
the line printer system. For each line printer configured in /etc/printcap (the line printer description data- 
base), lpc may be used to: 

° disable or enable a printer, 

* disable or enable a printer’s spooling queue, 

° rearrange the order of jobs in a spooling queue, 

• find the status of printers, and their associated spooling queues and printer daemons. 

Without any arguments, lpc works interactively and prompts for commands from the standard input. If 
arguments are supplied, lpc interprets the first argument as a command and the remaining arguments as 
parameters to the command. The standard input may be redirected so that lpc reads commands from a file. 
Commands may be abreviated; the following is the list of recognized commands. Note that the printer 
parameter in the commands is specified just by the name of the printer (printronix for example), not by 
— Pprintronix as you would specify it to the Ipr or Ipq commands. 

? [ command ... ] 
help [ command ... ] 

Display a short description of each command specified in the argument list, or, if no arguments are 
given, a list of the recognized commands. 

abort { all | printer ... } 

Terminate an active spooling daemon on the local host immediately and then disable printing 
(preventing new daemons from being started by Ipr) for the specified printers. The abort com- 
mand can only be used by the super-user. 

clean { all | printer ... } 

Remove all files beginning with ‘cf , ‘tf’, or ‘df from the specified printer queue(s) on the local 
machine. The clean command can only be used by the super-user. 

enable { all | printer ... } 

Enable spooling on the local queue for the listed printers, so that Ipr can put new jobs in the spool 
queue. The enable command can only be used by the super-user. 

exit 

quit 

Exit from lpc. 
disable { all | printer ... } 

Turn the specified printer queues off. This prevents new printer jobs from being entered into the 
queue by Ipr. The disable command can only be used by the super-user. 

restart { all | printer ... } 

Attempt to start a new printer daemon. This is useful when some abnormal condition causes the 
daemon to die unexpectedly leaving jobs in the queue. Lpq reports that there is no daemon 
present when this condition occurs. 

start { all | printer ... } 

Enable printing and start a spooling daemon for the listed printers. The start command can only 
be used by the super-user. 

status [ all ] [ printer ... ] 

Display the status of daemons and queues on the local machine, 
stop { all | printer ... } 
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Stop a spooling daemon after the current job completes and disable printing. The stop command 
can only be used by the super-user. 

topq printer [jobnum ...] [user ...] 

Move the print job(s) specified by jobnum or those job(s) belonging to user to the top (head) of the 
printer queue. The topq command can only be used by the super-user. 

FILES 

/etc/printcap printer description file 
/usr/spool/* spool directories 
/usr/spool/*/lock lock file for queue control 

SEE ALSO 

lpd(8), lpr(l), lpq(l), lprm(l), printcap(5) 


DIAGNOSTICS 

?Ambiguous command 
?Invalid command 
?Privileged command 


abreviation matches more than one command 
no match was found 

command can be executed by super-user only 


544 


Last change: 1 February 1985 


Sun Release 3.0 



LPD ( 8 ) 


MAINTENANCE COMMANDS 


LPD ( 8 ) 


NAME 

lpd - line printer daemon 
SYNOPSIS 

/usr/lib/lpd [ -1 ] [ -L logfile ] [ port # ] 

DESCRIPTION 

Lpd is the line printer daemon (spool area handler) and is normally invoked at boot time from the rc(8) file. 
It makes a single pass through the printcap(5) file to find out about the existing printers and prints any files 
left after a crash. It then uses the system calls listen^ 2) and accept (2) to receive requests to print files in the 
queue, transfer files to the spooling area, display the queue, or remove jobs from the queue. In each case, it 
forks a child to handle the request so the parent can continue to listen for more requests. The Internet port 
number used to rendezvous with other processes is normally obtained with getservent(5N) but can be 
changed with the port # argument. The — L option changes the file used for writing error conditions from the 
system console to logfile. The -1 flag causes lpd to log valid requests received from the network. This can 
be useful for debugging purposes. 

Access control is provided by two means. First, all requests must come from one of the machines listed in 
the file / etc / hosts, equiv. Second, if the “rs” capability is specified in the printcap entry for the printer 
being accessed, Ipr requests will only be honored for those users with accounts on the machine with the 
printer. 

The file lock in each spool directory is used to prevent multiple daemons from becoming active simultane- 
ously, and to store information about the daemon process for lpr{ 1), lpq( 1), and lprm( 1). After the dae- 
mon has successfully set the lock, it scans the directory for files beginning with cf. Lines in each c/file 
specify files to be printed or non-printing actions to be performed. Each such line begins with a key char- 
acter to specify what to do with the remainder of the line. 

J Job Name. String to be used for the job name on the burst page. 

C Classification. String to be used for the classification line on the burst page. 

L Literal. The line contains identification info from the password file and causes the banner page to 
be printed. 

T Title. String to be used as the title for pr(l). 

H Host Name. Name of the machine where Ipr was invoked. 

P Person. Login name of the person who invoked Ipr. This is used to verify ownership by Iprm. 

M Send mail to the specified user when the current print job completes, 

f Formatted File. Name of a file to print which is already formatted. 

1 Like ‘ ‘f ’ but passes control characters and does not make page breaks, 
p Name of a file to print using pr (1 ) as a filter. 

t Troff File. The file contains troff (l) output (C/A/T phototypesetter commands), 

d DVI File. The file contains TeX output (DVI format from Stanford), 
g Graph File. The file contains data produced by plot( 3X). 

c Cifplot File. The file contains data produced by cifplot. 

v The file contains a raster image. 

r The file contains text data with FORTRAN carriage control characters. 

1 Troff Font R. Name of the font file to use instead of the default. 

2 Troff Font I. Name of the font file to use instead of the default. 

3 Troff Font B. Name of the font file to use instead of the default. 

4 Troff Font S. Name of the font file to use instead of the default. 
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W Width. Changes the page width (in characters) used by pr{ 1) and the text filters. 

I Indent. The number of characters to indent the output by (in ascii). 

U Unlink. Name of file to remove upon completion of printing. 

N File name. The name of the file which is being printed, or a blank for the standard input (when Ipr 

is invoked in a pipeline). 

If a file can not be opened, a message will be placed in the log file (normally the console). Lpd will try up 
to 20 times to reopen a file it expects to be there, after which it will skip the file to be printed. 

Lpd uses flock (2) to provide exclusive access to the lock file and to prevent multiple deamons from becom- 
ing active simultaneously. If the daemon should be killed or die unexpectedly, the lock file need not be 
removed. The lock file is kept in a readable ASCII form and contains two lines. The first is the process id 
of the daemon and the second is the control file name of the current job being printed. The second line is 
updated to reflect the current status of lpd for the programs lpq(l) and lprm( 1). 

FILES 

/etc/printcap 
/usr/spool/* 

/dev/lp* 

/etc/hosts.equiv 

SEE ALSO 

lpc(8), pac(8), lpr(l), lpq(l), lprm(l), printcap(5) 

4.2BSD Line Printer Spooler Manual 


printer description file 
spool directories 
line printer devices 

lists machine names allowed printer access 
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NAME 

makedbm - make a yellow pages dbm file 
SYNOPSIS 

makedbm [ — i yp_input Jile ] [ — o yp_output_name ] [ -d yp_domain_name ] [ — m ypjnaster name ] 
infile outfile 

makedbm [ — u dbmfilename ] 

DESCRIPTION 

makedbm takes infile and converts it to a pair of files in dbm{ 3X) format, namely outfile .pag and outfile .dir. 
Each line of the input file is converted to a single dbm record. All characters up to the first tab or space 
form the key, and the rest of the line is the data. If a line ends with \, then the data for that record is contin- 
ued on to the next line. It is left for the clients of the yellow pages to interpret #; makedbm does not itself 
treat it as a comment character, infile can be -, in which case standard input is read. 

makedbm is meant to be used in generating dbm files for the yellow pages, and it generates a special entry 
with the key ypjastjnodified, which is the date of infile (or the current time, if infile is -). 

OPTIONS 

-i Create a special entry with the key ypjnput Jile. 

-o Create a special entry with the key yp_output_name . 

-d Create a special entry with the key yp_domain_name . 

-m Create a special entry with the key ypjnaster name. If no master host name is specified, 

ypjnaster name will be set to the local host name. 

-u Undo a dbm file. That is, print out a dbm file one entry per line, with a single space separating 
keys from values. 

EXAMPLE 

It is easy to write shell scripts to convert standard files such as letclpasswd to the key value form used by 
makedbm. For example, 

#!/bin/awk -f 

BEGIN { FS = OFS = ”\t"; } 

{ print $1, $0 } 

takes the letclpasswd file and converts it to a form that can be read by makedbm to make the yellow pages 
file passwd.byname . That is, the key is a username, and the value is the remaining line in the letclpasswd 
file. 

SEE ALSO 

dbm(3X), yppasswd(l) 
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NAME 

MAKEDEV - make system special files 
SYNOPSIS 

/dev/MAKEDEV device ... 

DESCRIPTION 

MAKEDEV is a shell script normally used to install special files. It resides in the /dev directory, as this is 
the normal location of special files. Arguments to MAKEDEV are usually of the form device-name ? where 
device-name is one of the supported devices listed in section 4 of the manual and “?’ is a logical unit 
number (0-9). A few special arguments create assorted collections of devices and are listed below. 

std Create the standard devices for the system; for example, /dev/console, /dev/tty. 

local Create those devices specific to the local site. This request runs the shell file 
/dev/MAKEDEV. local. Site specific commands, such as those used to setup dialup lines as ‘ttyd?’ 
should be included in this file. 

Since all devices are created using mknod( 8), this shell script is useful only to the super-user. 
DIAGNOSTICS 

Either self-explanatory, or generated by one of the programs called from the script. Use sh - 
x MAKEDEV in case of trouble. 

SEE ALSO 

intro(4), config(8), mknod(8) 
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NAME 

makekey - generate encryption key 
SYNOPSIS 

/usr/lib/makekey 

DESCRIPTION 

Makekey improves the usefulness of encryption schemes depending on a key by increasing the amount of 
time required to search the key space. It reads 10 bytes from its standard input, and writes 13 bytes on its 
standard output. The output depends on the input in a way intended to be difficult to compute (that is, to 
require a substantial fraction of a second). 

The first eight input bytes (the input key) can be arbitrary ASCII characters. The last two (the salt) are best 
chosen from the set of digits, upper- and lower-case letters, and V and 7\ The salt characters are repeated 
as the first two characters of the output. The remaining 1 1 output characters are chosen from the same set 
as the salt and constitute the output key. 

The transformation performed is essentially the following: the salt is used to select one of 4096 crypto- 
graphic machines all based on the National Bureau of Standards DES algorithm, but modified in 4096 dif- 
ferent ways. Using the input key as key, a constant string is fed into the machine and recirculated a 
number of times. The 64 bits that come out are distributed into the 66 useful key bits in the result. 

Makekey is intended for programs that perform encryption (for instance, ed and crypt (l)). Usually 
makekey’s input and output will be pipes. 

SEE ALSO 

crypt(l), ed(l) 
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NAME 

mkfs - construct a file system 
SYNOPSIS 

/etc/mkfs special size [ nsect ] [ ntrack ] [ blksize ] [ fragsize ] [ ncpg ] [ minfree ] [ rps ] [ nbpi ] 
DESCRIPTION 

N.B.: file system are normally created with the newfs( 8) command. 

Mkfs constructs a file system by writing on the special file special. The numeric size specifies the number 
of sectors in the file system. Mkfs builds a file system with a root directory and a lost+found directory (see 
fsck( 8)). The number of i-nodes is calculated as a function of the file system size. No boot program is ini- 
tialized by mkfs (see newfs( 8)). 

OPTIONS 

The optional arguments allow fine tune control over the parameters of the file system. 

Nsect specify the number of sectors per track on the disk. 

Ntrack specify the number of tracks per cylinder on the disk. 

Blksize gives the primary block size for files on the file system. It must be a power of two, currently 
selected from 4096 or 8192. 

Fragsize 

gives the fragment size for files on the file system. The fragsize represents the smallest amount of 
disk space that will be allocated to a file. It must be a power of two currently selected from the 
range 512 to 8192. 

Ncpg specifies the number of disk cylinders per cylinder group. This number must be in the range 1 to 
32. 

Minfree 

specifies the minimum percentage of free disk space allowed. Once the file system capacity 
reaches this threshold, only the super-user is allowed to allocate disk blocks. The default value is 
10 %. 

rps If a disk does not revolve at 60 revolutions per second, this parameter may be specified. 

nbpi Number of bytes for which one i-node block is allocated. This parameter is currently set at one i- 

node block for every 2048 bytes. 

Users with special demands for their file systems are referred to the paper cited below for a discussion of 
the tradeoffs in using different configurations. 

SEE ALSO 

fs(5), dir(5), fsck(8), newfs(8), tunefs(8) 

McKusick, Joy, Leffler; A Fast File System for Unix, System Internals Manual for the Sun Workstation. 
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NAME 

mknod - build special file 
SYNOPSIS 

/etc/mknod name [ c ] [ b ] major minor 
DESCRIPTION 

Mknod makes a special file. The first argument is the name of the entry. The second is b if the special file 
is block-type (disks, tape) or c if it is character-type (other devices). The last two arguments are numbers 
specifying the major device type and the minor device (for example, unit, drive, or line number). 

Mknod is only for use by system configuration people. Normally you should use Idev/MAKEDEV instead 
when making special files. 

SEE ALSO 

mknod(2), makedev(8) 
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NAME 

mkproto - construct a prototype file system 
SYNOPSIS 

/usr/etc/mkproto special proto 
DESCRIPTION 

Mkproto is used to bootstrap a new file system. First a new file system is created using newfs( 8). Mkproto 
is then used to copy files from the old file system into the new file system according to the directions found 
in the prototype file proto. The prototype file contains tokens separated by spaces or new lines. The first 
tokens comprise the specification for the root directory. File specifications consist of tokens giving the 
mode, the user-id, the group id, and the initial contents of the file. The syntax of the contents field depends 
on the mode. 

The mode token for a file is a 6 character string. The first character specifies the type of the file. (The 
characters -bed specify regular, block special, character special and directory files respectively.) The 
second character of the type is either u or - to specify set-user-id mode or not. The third is g or - for the 
set-group-id mode. The rest of the mode is a three digit octal number giving the owner, group, and other 
read, write, execute permissions, see chmod{ 1). 

Two decimal number tokens come after the mode; they specify the user and group ID’s of the owner of the 
file. 

If the file is a regular file, the next token is a pathname whence the contents and size are copied. 

If the file is a block or character special file, two decimal number tokens follow which give the major and 
minor device numbers. 

If the file is a directory, mkproto makes the entries . and .. and then reads a list of names and (recursively) 
file specifications for the entries in the directory. The scan is terminated with the token $. 

A sample prototype specification follows: 

d— 777 3 1 


d— 

777 3 1 

sh 

755 3 1 /bin/sh 

ken 

d— 755 6 1 


$ 

bO 

b— 644 3 1 0 0 

cO 

c— 644 3 1 0 0 


$ 

$ 

SEE ALSO 

fs(5), dir(5), fsck(8), newfs(8) 

BUGS 

There should be some way to specify links. 

There should be some way to specify bad blocks. 

Mkproto can only be run on virgin file systems. It should be possible to copy files into existent file sys- 
tems. 
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NAME 

monitor - system PROM monitor and command interpreter 
SYNOPSIS 

LI -a 
BREAK 

DESCRIPTION 

The CPU board of the Sun workstation contains a PROM (or set of PROMs), called the monitor, that con- 
trols the system during startup. The monitor tests the system and then searches for and attempts to boot 
UNIX. If you interrupt the boot procedure, or by typing either Ll-a or BREAK, it issues the prompt: 

> 

and accepts commands interactively. 

COMMANDS 

A[n] [ action . . .] 

open A-register (cpu address register) n, and perform indicated actions, n can be from 0 to 7. The 
default is 0. action is a data value in hex; a non-hex character terminates command input. 

B [device [(c,u,p)] ] [pathname ] 

boot. Resets appropriate parts of the system, then bootstraps. This allows bootstrap loading of 
programs from various devices (such as a disk, tape, or Ethernet connection). 

device is one of: 

ie Intel Ethernet 

sd SCSI disk 

st SCSI 1/4" tape 

mt Tape Master 9-track 1/2" tape 
xt Xylogics 1/2" tape 

xy Xylogics 440/450 disk 

c is a controller number (0 if only one controller), 
u is a unit number (0 if only one driver), and, 
p is a partition. 
pathname 

is a pathname for a program such as I standi diag. vmunix is the default. 

B with no arguments will cause a default boot, either from the disk, or from the Ethernet con- 
troller. 

B? displays all boot devices and their device arguments. 

C [addr] 

continue a program. When given, addr is the address at which execution will begin. The default is 
the current PC. Registers are restored to the values shown by A, D, and R commands. 

D [n ] [action . . . ] 

open D-register (cpu data register) n, and perform indicated actions, n can be from 0 to 7. The 
default is 0. 

E [addr] [par am] 

open the 16 bit word at addr (default zero) in the address space defined by the S command. 

F addrl addr2 [pattern ] [size ] Sun 3 only. 

Fill address space from (lower) addrl to (higher) addr2 with the constant, pattern, specified by 
size : 
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b byte format (the default), 

w word format, or 

1 long word format. 

For example, the following command fills the address block from 0x1000 to 0x2000 with the word 
pattern, OxABCD: 

F 1000 2000 ABCD W 

G \addr] 

Start the program by executing a subroutine call to the address addr if given, or else to the current 
PC. The values of the address and data registers are undefined. The status register is set to 0x2700. 

GO When the monitor is running as a result of being interrupted, force a panic and produce a crash 
dump. 

G4 When the monitor is running as a result of being interrupted, force a kernel stack trace. 

H Sun 3 only 

Display the menu of monitor commands, and their descriptions. 

K [number ] 

If number is: 

0 cpu reset only. This is the default 

1 reset cpu and mmu. 

KB display the system banner. 

L [addr] [actions] 

open the long (32 bit) word at memory address addr (default zero) in the address space defined by 
the S command (below). 

M [addr] [actions] 

open the segment map entry that maps virtual address addr (default zero) in the address space 
defined by the S command (below). The segment map address is the virtual address field from 
address bit 27 thru bit 17 of the virtual address presented by the cpu to the mmu. 

O [addr] [actions] 

open the byte location specified by addr (default zero) in the address space defined by the S com- 
mand below. 

P [addr] [actions] 

open the page map entry that maps virtual address addr (default zero) in the address space defined 
by the S command. 

Q [addr ] [actions ] Sun 3 only. 

open the EEPROM address addr (default zero) in the EEPROM address space. All addresses are 
referenced from the beginning or base of the EEPROM in physical address space, and a limit 
check is performed to insure that no address beyond the EEPROM physical space is accessed. 
This command is used to examine/modify configuration parameters specifying such things as 
amount of memory to test during self test, whether to display a standard or custom banner, if a 
serial port (A or B) is to be the system console, etc. 

R [reg] [actions] 

open the miscellaneous registers, reg can be one of: 

SS (68010 Supervisor Stack Pointer), 

IS (68020 Interrupt Stack Pointer), 

MS (68020 Master Stack Pointer), 
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US (User Stack Pointer), 

SF (Source Function code), 

DF (Destination Function code), 

VB (Vector Base), 

SC (System Context), 

UC (User Context), 

SR (Status Register), and 

PC (Program Counter). 

Alterations to these registers (except SC and UC) do not take effect until the next C command. 

S [code] set or query the address space to be used by subsequent memory access commands, code is one of: 

0 undefined. 

1 user data space. 

2 user program space. 

3 user control space. 

4 undefined. 

5 supervisor data space. 

6 supervisor program space. 

7 supervisor control space. 

T [command] Sun 3 only 

trace command. Works with standalone programs that do not affect interrupt vectors. 

U [arg] manipulate the serial ports and switches the current operator I/O device, arg can have any of the 
following values ( [AB] indicates one of A or B): 

[AB] select serial port A or B as input and output device 

[ABJio select serial port A or B as input and output device 

[AB]i select serial port A or B for input only 

[AB]o select serial port A or B for output only 

k select keyboard for input 

ki select keyboard for input 

s select screen for output 

so select screen for output 

ks,sk select keyboard for input and screen for output 

[AB]# set speed of serial port A (or B) to # (such as 1200,9600,..) 

e echo input to output 

ne don’t echo input to output 

u addr set virtual serial port address to addr . 

If no serial port is specified when changing speeds, the current input device is changed. 

At power-up, the following default settings are used: the default console input device is the Sun 
keyboard or if the keyboard is unavailable, serial port A. The default console output device is the 
Sun screen or if the graphics board is unavailable, serial port A. All serial ports are set to 9600 
Baud. 
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V addrl addr2 [size] Sun 3 only 

display the contents of addresses from (lower) addrl to (higher) address addr2 in the format 
specified by size : 

b byte format (the default), 

w word format, or 

1 long word format. 

Enter return to pause for viewing; enter another return character resume the display. To 
terminate the display at any time, press the space bar. Or, you can use 'S and ‘Q to stop 
and start the display. 

For example, the following command displays the contents of virtual address space from 
address 0x1000 to 0x2000 in word format: 

V 1000 2000 W 

W [addr ] [ arg ] Sun 3 only. 

vector, arg is one of: 

print prints the contents of virtual address addr as a string. 

When the monitor is running as a result of being interrupted: 
dump initiates a crash dump, 
trace produces a stack trace. 

X Sun 3 only 

display a menu of extended tests to be presented, with loop and print options also selectable. 
These test commands are provided to permit additional testing of such things as the I/O port con- 
nectors at the handle edge of the CPU board, Video memory, workstation memory and the works- 
tation keyboard, as well as permit the boot device paths to be tested. 

Z [addr] Sun 3 only. 

set a breakpoint at addr in the address space selected by the S command. 
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NAME 

mount, umount - mount and dismount filesystems 
SYNOPSIS 

/etc/mount 

/etc/mount -a[fv] [ -t type ] 

/ etc/mount [ -f [ rv ] [ to type options ] fsname \ dir ] 

/etc/mount -p 

/etc/umount [ -a [ v ] ] [fsname | dir]] ... 

/etc/umount [ — v ] [fsname | ] ] 

DESCRIPTION 

mount announces to the system that a filesystem fsname is to be attached to the file tree at the directory dir. 
The directory dir must already exist. It becomes the name of the newly mounted root. The contents of dir 
are hidden until the filesystem is unmounted. If fsname is of the form host:path mount assumes that the 
filesystem type is nfs{ 4). 

Umount announces to the system that the filesystem fsname previously mounted on directory dir should be 
removed. Either the filesystem name or the mounted-on directory may be used. 

mount and umount maintain a table of mounted filesystems in letclmtab, described in mtab( 5). If invoked 
without an argument, mount displays the table. If invoked with only one of fsname or dir mount searches 
the file letclfstab (see f stab (5)) for an entry whose dir or fsname field matches the given argument For 
example, if this line is in letclfstab-. 

/dev/xyOg /usr 4.2 rw 1 1 

then the commands mount /usr and mount /dev/xyOg are shorthand for mount /dev/xyOg /usr 
MOUNT OPTIONS 

-a Attempt to mount all the filesystems described in letclfstab. In this case, fsname and dir are taken 
from letclfstab. If a type is specified all of the filesystems in letclfstab with that type is mounted. 

-f Fake a new letclmtab entry, but do not actually mount any filesystems. 

-r Mount the specified filesystem read-only. This is a shorthand for: 

mount -o ro fsname dir 

Physically write-protected and magnetic tape filesystems must be mounted read-only, or errors 
occur when access times are updated, whether or not any explicit write is attempted. 

-v Verbose — mount displays a message indicating the filesystem being mounted. 

-p Print the list of mounted filesystems in a format suitable for use in letclfstab. 

-t The next argument is the filesystem type. The accepted types are: 4.2, and nfs; seefstab(5) for a 

description of these filesystem types. 

-o Specify options , a list of comma seperated words from the list below. Some options are valid for 
all filesystem types, while others apply to a specific type only. 

options valid on all file systems (the default is rw,suid): 

rw read/write. 

ro read-only. 

suid set-uid execution allowed. 

nosuid set-uid execution not allowed. 

options specific to 4.2 file systems (the default is noquota), 
quota usage limits enforced. 
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noquota usage limits not enforced. 

options specific to nfs (NFS) file systems (the defaults are: 

fg,retry=l,timeo=7,retrans=4,port=NFS_PORT,hard 
with defaults for rsize and wsize set by the kernel): 
bg if the first attempt fails, retry in the background, 

fg retry in foreground. 

retry=n set number of failure retries to n. 
rsize=n set read buffer size to n bytes. 
wsize=n set write buffer size to n bytes. 
timeo=n set NFS timeout to n tenths of a second. 
retrans=n set number of NFS retransmissions to n. 
port=n set server IP port number to n. 
soft return error if server doesn’t respond, 

hard retry request until server responds. 

The bg option causes mount to run in the background if the server’s mountd{%) does not respond. 
mount attempts each request retry=n times before giving up. Once the filesystem is mounted, 
each nfs request made in the kernel waits timeo=n tenths of a second for a response. If no 
response arrives, the time-out is multiplied by 2 and the request is retransmitted. When retrans=n 
retransmissions have been sent with no reply a soft mounted filesystem returns an error on the 
request and a hard mounted filesystem retries the request. The number of bytes in a read or write 
request can be set with the rsize and wsize options. 

UMOUNT OPTIONS 

-a Attempt to unmount all the filesystems currently mounted. In this case, fsname is taken from 
/etc/mtab. 

-v Verbose — umount displays a message indicating the filesystem being unmounted. 

EXAMPLES 

mount /dev/xyOg /usr 
mount -ft 4.2 /dev/ndO / 
mount -at 4.2 

mount -t nfs serv:/usr/src /usr/src 
mount serv:/usr/src /usr/src 
mount -o hard serv:/usr/src /usr/src 
mount -p > /etc/fstab 

FILES 

/etc/mtab mount table 

/etc/fstab filesystem table 

SEE ALSO 

mount(2), nfsmount(2), unmount(2), fstab(5), mountd(8c), nfsd(8c) 

BUGS 

Mounting filesystems full of garbage crashes the system. 

No more than one ND client should mount an ND disk partition "read-write" or the file system may 
become corrupted. 


mount a local disk 
fake an entry for nd root 
mount all 4.2 filesystems 
mount remote filesystem 
same as above 

same as above but hard mount 
save current mount state 
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NAME 

mountd - NFS mount request server 
SYNOPSIS 

/ usr/etc/rpc.mountd 
DESCRIPTION 

mountd is an rpc(4)serverv/hichanswers&le It reads the file /etc/exports (see exports (5) ) todetermine which 
which machines and users. It also provides information about which clients have file systems mounted. 
This information can be printed using the showmount(%)command. 

The mountd daemon is normally invoked by inetd( 8C). 

SEE ALSO 

nfs(4), rpc(4), services(5), inetd(8), exports(5), showmount(8) 
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NAME 

ncheck - generate names from i-numbers 
SYNOPSIS 

/usr/etc/ncheck [ -i numbers ] [ -a ] [ -s ] [ filesystem ] 

DESCRIPTION 

N.B.: For most normal file system maintenance, the function of ncheck is subsumed by fsck( 8). 

Ncheck with no argument generates a pathname versus i-number list of all files on a set of default file sys- 
tems. Names of directory files are followed by 7.’. 

A file system may be specified by the optional filesystem argument 

The report is in no useful order, and probably should be sorted. 

OPTIONS 

— i numbers 

Report only those files whose i-numbers follow. 

-a Print the names V and which are ordinarily suppressed. 

— s Report only special files and files with set-user-ID mode. This is intended to discover concealed 

violations of security policy. 

SEE ALSO 

sort(l), dcheck(8), fsck(8), icheck(8) 

DIAGNOSTICS 

When the filesystem structure is improper, *??’ denotes the ‘parent’ of a parentless file and a pathname 
beginning with \ . denotes a loop. 
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NAME 

nd - network disk control 

SYNOPSIS 

/etc/nd [ command ] 

DESCRIPTION 

The nd command controls the network disk service of the kernel as described in nd{ 4p). A single com- 
mand may be given on the command line; if none is given then the standard input is read for a list of com- 
mands. Typically, the file tetdnd.local is used for input. Lines beginning with *#’ are considered to be 
comments. 

The available commands are: 

user hostname hisunit mydev my off my size mylunit 

For the client hostname transform incoming requests for hisunit into server device mydev at offset 
myoff and size mysize sectors. Idev/ndlmylunit provides a local name for this disk “subpartition”. 
If mysize is -1, then this user unit is equivalent to the entire filesystem partition mydev (no subpar- 
tioning is done.) If mylunit is -1 then no local name is needed for this user unit; this is usually the 
case with a swap unit, or a unit represented by an entire filesystem. If hostname is a numeric zero, 
hisunit refers to a public unit. Since nd assists diskless clients in booting, the files (or their 
equivalent YP maps) letclhosts and letc/ethers are used to map the users’ hostnames to their IP 
addresses and ethemet addresses, respectively. 

version versionnumber 

The version command gives the level of configuration of the server. Occasionally the need arises 
to reorganize or reload the diskless partitions. Since the clients will rewrite locally cached blocks, 
they must be kept from writing their filesystems until they reboot. Before such a reorganization 
occurs, the system manager should warn diskless users to save files and halt their machines. 
Modification of the partitions should occur with the disk server off. After modification is com- 
plete, versionnumber should be incremented to force users to reboot. 

son 

Starts the network disk server. This command should be issued after all user, version, and ether 
commands. 

sow 

Stops the disk server until a subsequent son command. 

clear 

Stops the disk server and clears all user and ether information, 
serverat hostname 

Systems with disks may use the serverat command to specify a disk server if they wish to use a 
network disk in addition to their locally attached disk. Even then, this command is only necessary 
if they wish to use a public network disk, or if they wish to change network disk servers. 

FILES 

/etc/nd.local 

/etc/hosts 

/etc/ethers 

SEE ALSO 

nd(4P) 

BUGS 

No sanity checking of disk partitions is done. 
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NAME 

netstat — show network status 
SYNOPSIS 

netstat [ — m|— i| -h|-r ] [ -a ] [ -n ] [ -s ] [ -t ] [ -A ] [ interval ] [ system ] [ core ] 

DESCRIPTION 

Netstat symbolically displays the contents of various network-related data structures. 

The arguments, system and core allow substitutes for the defaults ‘/vmunix’ and ‘/dev/kmem’. 

If an interval is specified, netstat continuously displays the information regarding packet traffic on the 
configured network interfaces, pausing interval seconds before refreshing the screen. 

There are a number of display formats, depending on the information that netstat presents. The display for- 
mats are controlled by the options listed below and are described there. 

OPTIONS 

Not all of the options listed here can be used in combination. Some of the options select the information to 
be displayed, and some of the options further qualify that specific display. Netstat checks its options in the 
order -m (memory management statistics), -i (interface statistics), -h (host table state), and -r (routing 
tables), and presents a display for only one of these options. 

The default display, for active sockets, shows the local and remote addresses, send and receive queue sizes 
(in bytes), protocol, and, optionally, the internal state of the protocol. Other display formats are controlled 
by the options listed below. 

-m Show statistics recorded by the memory management routines (the network manages a “private 
share’ ’ of memory) 

-i Show the state of interfaces which have been auto-configured (interfaces statically configured into 
a system, but not located at boot time are not shown) The interface display provides a table of 
cumulative statistics regarding packets transferred, errors, and collisions. The network address 
(currently Internet specific) of the interface and the maximum transmission unit (“mtu”) are also 
displayed. 

-h Show the state of the IMP host table. This does not work in an environment where the IMP host 
tables do not exist. 

-r Show the routing tables. The routing table display indicates the available routes and their status. 
Each route consists of a destination host or network and a gateway to use in forwarding packets. 
The flags field shows the state of the route (“U” if “up”), and whether the route is to a gateway 
(“G”). Direct routes are created for each interface attached to the local host. The refcnt field 
gives the current number of active uses of the route. Connection oriented protocols normally hold 
on to a single route for the duration of a connection while connectionless protocols obtain a route 
then discard it. The use field provides a count of the number of packets sent using that route. The 
interface entry indicates the network interface utilized for the route. 

Options listed below provide further qualification for the display formats listed above. 

-A Show the address of any associated protocol control blocks; used for debugging. 

-a Show the state of all sockets; normally sockets used by server processes are not shown 

— n Show network addresses as numbers (normally netstat interprets addresses and attempts to display 

them symbolically). 

-s Show per-protocol statistics. When used with the -r option, the -s option displays routing statis- 
tics. 

-t Add timer information to the interface display. 
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FURTHER NOTES 

Address formats are of the form “host.port” or “network.port” if a socket’s address specifies a network 
but no specific host address. When known the host and network addresses are displayed symbolically 
according to the data bases letc/hosts and /etc/networks, respectively. If a symbolic name for an address is 
unknown, or if the -n option is specified, the address is printed in the Internet “dot format”; refer to 
inet(3N) for more information regarding this format. Unspecified, or “wildcard”, addresses and ports 
appear as 

When netstat is invoked with an interval argument, it displays a running count of statistics related to net- 
work interfaces. This display consists of a column summarizing information for all interfaces, and a 
column for the interface with the most traffic since the system was last rebooted. Every 24th line of each 
screen of information contains a summary since the system was last rebooted. Subsequent lines of output 
show values accumulated over the preceding interval. 

SEE ALSO 

iostat(8), vmstat(8), hosts(5), networks(5), protocols(5), services(5), trpt(8C) 

BUGS 

The notion of errors is ill-defined. Collisions mean something else for the IMP. 

The kernel’s tables can change while netstat is examining them, creating incorrect or partial displays. 
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NAME 

newaliases - rebuild the data base for the mail aliases file 

SYNOPSIS 

newaliases 

DESCRIPTION 

Newaliases rebuilds the random access data base for the mail aliases file lusrllibl aliases. It must be run 
each time lusrllibl aliases is changed in order for the change to take effect. 

SEE ALSO 

aliases(5), sendmail(8) 
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NAME 

newfs - construct a new file system 
SYNOPSIS 

/etc/newfs [ -v ] [ -n ] [ mkfs-options ] special [ disk-type ] 

DESCRIPTION 

Newfs is a “friendly” front-end to the mJfs( 8) program. On the VAX, newfs will look up the type of disk a 
file system is being created on in the disk description file letc/disktab; on the Sun the disk type is deter- 
mined by reading the disk label. Newfs then calculates the appropriate parameters to use in calling mlfs, 
then builds the file system by forking mlfs and, if the file system is a root partition, installs the necessary 
bootstrap programs in the initial 16 sectors of the device. 

OPTIONS 

— n Do not install the bootstrap programs. 

-v newfs prints out its actions, including the parameters passed to mlfs. 

Options which may be used to override default parameters passed to mlfs are: 

-s size The size of the file system in sectors. 

-b block-size 

The block size of the file system in bytes. 

-f frag-size 

The fragment size of the file system in bytes. 

-t #tracks/cylinder 
-c #cylinders/group 

The number of cylinders per cylinder group in a file system. The default value used is 16. 

-m free space % 

The percentage of space reserved from normal users; the minimum free space threshhold. The 
default value used is 10%. 

-r revolutions/minute 

The speed of the disk in revolutions per minute (normally 3600). 

FILES 

/etc/disktab for disk geometry and file partition information (VAX only) 

/etc/mkfs to actually build the file system 

/usr/mdec for boot strapping programs 

SEE ALSO 

fs(5), fsck(8), tunefs(8) 

The Sun UNIX File System in the Sun System Internals Manual. 
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NAME 

nfsd, biod - NFS daemons 

SYNOPSIS 

/etc/nfsd [nservers] 

/etc/biod [nservers] 

DESCRIPTION 

Nfsd starts the NFS (4) server daemons that handle client filesystem requests. Nservers is the number of file 
system request daemons to start. This number should be based on the load expected on this server. Four 
seems to be a good number. 

Biod starts nservers asynchronous block I/O daemons. This command is used on a NFS client to buffer 
cache handle read-ahead and write-behind. The magic number for nservers in here is also four. 

SEE ALSO 

nfs(4), rpc(4), mountd(8c), exports(5) 
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NAME 

nfsstat - Network File System statistics 

SYNOPSIS 

nfsstat [ -csnrdz ] 

DESCRIPTION 

Nfsstat displays statistical information about the Network File System (NFS), Remote Procedure Call 
(RPC), and Network Disk (ND) interfaces to the kernel. It can also be used to reinitialize this information. 
If no options are given the default is 

nfsstat -csnr 

That is, print everything except ND information, and reinitialize nothing. 

OPTIONS 

-c Display client information. Only the client side NFS and RPC information will be printed. Can 
be combined with the -n and -r options to print client NFS or client RPC information only. 

-s Display server information. Works like the -c option above. 

-n Display NFS information. NFS information for both the client and server side will be printed. 
Can be combined with the -c and -s options to print client or server NFS information only. 

-r Display RPC information. Works like the -n option above. 

-d Display Network Disk (ND) information. 

-z Zero (reinitialize) statistics. Can be combined with any of the above options to zero particular sets 
of statistics after printing them. The user must have write permission on /dev/kmem for this option 
to work. 

FILES 

/vmunix system namelist 

/dev/kmem kernel memory 

SEE ALSO 

nfs(4) 
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NAME 

pac - printer/plotter accounting information 
SYNOPSIS 

/usr/etc/pac [ -P printer ] [ -p price ] [ -s ] [ -r ] [ -c ] [ name ... ] 

DESCRIPTION 

Pac reads the printer/plotter accounting files, accumulating the number of pages (the usual case) or feet 
(for raster devices) of paper consumed by each user, and printing out how much each user consumed in 
pages or feet and dollars. If any names are specified, then statistics are only printed for those users; usu- 
ally, statistics are printed for every user who has used any paper. 

OPTIONS 

— P printer 

Do accounting for the named printer. Normally, accounting is done for the default printer (site 
dependent) or the value of the PRINTER environment variable is used. 

-pprice Use the value price for the cost in dollars instead of the default value of 0.02. 

-c Sorted the output by cost; usually the output is sorted alphabetically by name. 

-r Reverse the sorting order. 

-s Summarize the accounting information on the summary accounting file; this summary is necessary 
since on a busy system, the accounting file can grow by several lines per day. 

FILES 

/usr/adm/?acct raw accounting files 

/usr/adm/?_sum summary accounting files 

BUGS 

The relationship between the computed price and reality is as yet unknown. 
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NAME 

ping - network debugging 
SYNOPSIS 

/usr/etc/ping host [ timeout ] 

DESCRIPTION 

Ping repeatedly sends an icmp echo packet to host and reports whether or not a reply was received. It 
keeps trying until timeout seconds have elapsed, or an answer is received. The default timeout is 20 
seconds. The host argument can be a name or an internet address. 

SEE ALSO 

icmp(4P) 
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NAME 

portmap - DARPA port to RPC program number mapper 

SYNOPSIS 

/usr/etc/rpc.portmap 

DESCRIPTION 

P ortmap is a server that converts RPC program numbers into DARPA protocol port numbers. It must be 
running in order to make RPC calls. 

When an RPC server is started, it will tell portmap what port number it is listening to, and what RPC pro- 
gram numbers it is prepared to serve. When a client wishes to make an RPC call to a given program 
number, it will first contact portmap on the server machine to determine the port number where RPC pack- 
ets should be sent. 

Normally, standard RPC servers are started by inetd(8c), so portmap must be started before inetd is 
invoked. 

SEE ALSO 

servers(5), rpcinfo(8), inetd(8) 

BUGS 

If portmap crashes, all servers must be restarted. 
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NAME 

pstat - print system facts 
SYNOPSIS 

/etc/pstat -aixptufT [ suboptions ] [ system [ corefile ] ] 

DESCRIPTION 

Pstat interprets the contents of certain system tables. If corefile is given, the tables are sought there, other- 
wise in Idevlkmem. The required namelist is taken from /vmunix unless system is specified. 

OPTIONS 

-a Under -p, describe all process slots rather than just active ones. 


-i 


Print the inode table including the associated vnode entries with these headings: 


LOC 

IFLAG 


IDEVICE 

INO 

MODE 

NLK 

UID 

SIZE/DEV 

VFLAG 


CNT 

SHC 

EXC 

TYPE 


The core location of this table entry. 

Miscellaneous inode state variables encoded thus: 

A inode access time must be corrected 

C inode has been changed 

L inode is locked 

R inode is being referenced 

T inode contains a pure text prototype 

U update time (fs( 5)) must be corrected 

W wanted by another process (L flag is on) 

Z someone waiting for an exclusive lock 

Major and minor device number of file system in which this inode resides. 

I-number within the device. 

Mode bits in octal, see chmod( 2). 

Number of links to this inode. 

User ID of owner. 

Number of bytes in an ordinary file, or major and minor device of special file. 
Miscellaneous vnode state variables encoded thus: 

R root of its file system 

S shared lock applied 

E exclusive lock applied 

T vnode is a pure text prototype 

Z proccess is waiting for a shared or exclusive lock 
Number of open file table entries for this vnode. 

Reference count of shared locks on the vnode. 

Reference count of exclusive locks on the vnode (this may be > 1 if, for example, a file 
descriptor is inherited across a fork). 

Vnode file type, either VNON (no type), VREG (regular), VDIR (directory), VBLK 
(block device), VCHR (character device), VLNK (symbolic link), VSOC (socket), or 
VBAD (bad). 


-x Print the text table with these headings: 

LOC The core location of this table entry. 

FLAGS Miscellaneous state variables encoded thus: 

P resulted from demand-page-from-inode exec format (see execve (2)) 
T ptrace(2) in effect 
W text not yet written on swap device 
L loading in progress 
K locked 

w wanted (L flag is on) 
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DADDR 

Disk address in swap, measured in multiples of 512 bytes. 

CADDR Head of a linked list of loaded processes using this text segment. 

RSS Resident set size, measured in pagesize units (2048K for a Sun 2; 8192 for a Sun 3). 
SIZE Size of text segment, measured in multiples of 5 12 bytes. 

VPTR Core location of corresponding vnode. 

CNT Number of processes using this text segment 
CCNT Number of processes in core using this text segment. 


-p Print process table for active processes with these headings: 

LOC The core location of this table entry. 

S Run state encoded thus: 

0 no process 

1 awaiting an event 

2 (abandoned state) 

3 runnable 

4 being created 

5 being terminated 

6 stopped under trace 

F Miscellaneous state variables, or-ed together (hexadecimal): 

0000001 loaded 

0000002 a system process (scheduler or page-out daemon) 

0000004 locked for swap out 

0000008 swapped out during process creation 

0000010 traced 

0000020 used in tracing 

0000040 user settable lock in core 

0000080 in page-wait 

0000 1 00 prevented from swapping during fork (2) 

0000200 restore old sigmask after taking signal 
0000400 exiting 
0000800 doing physical i/o 

0001000 process resulted from a vfork(2) which is not yet complete 
0002000 another flag for vfork(2) 

0004000 process has no virtual memory, as it is a parent in the context of vfork( 2) 
0008000 process is demand paging data pages from its text inode 
0010000 process has advised of sequential behavior with vadvise( 2) 

0020000 process has advised of anomalous behavior with vadvise (2) 

0040000 process is in a sleep which will timeout 
0080000 (unused) 

0100000 using old signal mechanism 
0200000 process is owed a profiling tick 
0400000 process is setting up a select^ 2) call 
0800000 Process is a login process 

1000000 Page tables for this process have changed (tlb is dirty) 

POIP number of pages currently being pushed out from this process. 

PRI Scheduling priority, see setpriority(2). 

SIG Signals received (signals 1-32 coded in bits 0-31), 

UID Real user ID. 

SLP Amount of time process has been blocked. 
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TIM Time resident in seconds; times over 127 coded as 127. 

CPU Weighted integral of CPU time, for scheduler. 

NI Nice level, see setpriority(2). 

PGRP Process number of root of process group (the opener of the controlling terminal). 

PID The process ID number. 

PPID The process ID of parent process. 

ADDR If in core, the page frame number of the first page of the ‘u-area’ of the process. If 
swapped out, the position in the swap area measured in multiples of 512 bytes. 

RSS Resident set size - the number of physical page frames allocated to this process. 

SRSS RSS at last swap (0 if never swapped). 

SIZE Virtual size of process image (data+stack) in multiples of 5 12 bytes. 

WCHAN 

Wait channel number of a waiting process. 

LINK Link pointer in list of runnable processes. 

TEXTP If text is pure, pointer to location of text table entry. 

-t Print table for terminals with these headings: 

RAW Number of characters in raw input queue. 

CAN Number of characters in canonicalized input queue. 

OUT Number of characters in putput queue. 

MODE See tty(4). 

ADDR Physical device address. 

DEL Number of delimiters (newlines) in canonicalized input queue. 

COL Calculated column position of terminal. 

STATE 

Miscellaneous state variables encoded thus: 

T delay timout in progress 

W waiting for open to complete 
O open 

C carrier is on 

B busy doing output 

A process is awaiting output 

X open for exclusive use 

H hangup on close 

PGRP Process group for which this is controlling terminal. 

DISC Line discipline; blank is old tty OTTYDISC or “new tty” for NTTYDISC or “net” for 
NETLDISC (see bk( 4)). 

-u print information about a user process; the next argument is its address as given by ps(l). The pro- 
cess must be in main memory. 

-f Print the open file table with these headings: 

LOC The core location of this table entry. 

TYPE The type of object the file table entry points to. 

FLG Miscellaneous state variables encoded thus: 

R open for reading 

W open for writing 

A open for appending 

S shared lock present 

X exclusive lock present 

I signal pgrp when data ready 
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CNT Number of processes that know this open file. 

MSG Number of references from message queue. 

DATA The location of the vnode table entry or socket for this file. 

OFFSET 

The file offset (see lseek{ 2)), or the core address of the associated socket structure. 

-s print information about swap space usage: the number of (kilobyte) blocks used and free is given as 
well as the number of used blocks which belong to text images — along with the maximum allocat- 
able process size and swap allocation sizes available. 

-T prints the number of used and free slots in the several system tables and is useful for checking to see 
how full system tables have become if the system is under heavy load. 

FILES 

/vmunix namelist 
/dev/kmem default source of tables 

SEE ALSO 

ps(l), stat(2), fs(5) 

K. Thompson, UNIX Implementation 

BUGS 

It would be very useful if the system recorded “maximum occupancy” on the tables reported by -T; even 
more useful if these tables were dynamically allocated. 
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NAME 

quot- summarize file system ownership 
SYNOPSIS 

/usr/etc/quot [ -acfhnv ] [filesystem ] 

DESCRIPTION 

Quot displays the number of blocks (1024 bytes) in the named filesystem currently owned by each user. 
OPTIONS 

-a Generate are report for all mounted file systems. 

-c Display three columns giving file size in blocks, number of files of that size, and cumulative total 
of blocks in that size or smaller file. 

-f Display count of number of files as well as space owned by each user. 

-h Estimate the number of blocks in the file — this doesn’t account for files with holes in them. 

-n Run the pipeline ncheck filesystem | sort +0n | quot -n filesystem to produce a list of all files 

and their owners. 

-v Display three columns containing the number of blocks not accessed in the last 30, 60, and 90 
days. 

FILES 

/etc/mtab mounted file systems 

/etc/passwd to get user names 

SEE ALSO 

ls(l),du(l) 
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NAME 

quotacheck - file system quota consistency checker 
SYNOPSIS 

/usr/etc/quotacheck [ -v ] filesystem... 

/usr/etc/quotacheck [ -v ] -a 

DESCRIPTION 

Quotacheck examines each file system, builds a table of current disk usage, and compares this table against 
that stored in the disk quota file for the file system. If any inconsistencies are detected, both the quota file 
and the current system copy of the incorrect quotas are updated (the latter only occurs if an active file sys- 
tem is checked). 

If the -a flag is supplied in place of any file system names, quotacheck will check all the file systems indi- 
cated in /etc/fstab to be read-write with disk quotas. 

Normally quotacheck reports only those quotas modified. If the -v option is supplied, quotacheck will 
indicate the calculated disk quotas for each user on a particular file system. 

Quotacheck expects each file system to be checked to have a quota file named quotas in the root directory. 
If none is present, quotacheck will ignore the file system. 

Quotacheck is normally run at boot time from the letc/rc. local file, see re (8), before enabling disk quotas 
with quotaon(8). 

Quotacheck accesses the raw device in calculating the actual disk usage for each user. Thus, the file sys- 
tems checked should be quiescent while quotacheck is running. 

FILES 

quotas quota file at the file system root 

/ etc/ mtab mounted file systems 

/etc/fstab default file systems 

SEE ALSO 

quotactl(2), quotaon(8) 
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NAME 

quotaon, quotaoff- turn file system quotas on and off 
SYNOPSIS 

/usr/etc/quotaon [ -\]filsys... 

/usr/etc/quotaon [ -v ] -a 
/usr/etc/quotaoff [ -v ] filsys... 

/usr/etc/quotaoff [ -v ] -a 
DESCRIPTION 

Quotaon announces to the system that disk quotas should be enabled on one or more file systems. The file 
systems specified must be mounted at the time. The file system quota files must be present in the root 
directory of the specified file system and be named quotas. The optional argument -v causes quotaon to 
print a message for each file system where quotas are turned on. If, instead of a list of file systems, a -a 
argument is given to quotaon, all file systems in /etc/fstab marked read-write with quotas will have then- 
quotas turned on. This is normally used at boot time to enable quotas. 

Quotaoff announces to the system that file systems specified should have any disk quotas turned off. As 
above, the -v forces a verbose message for each file system affected; and the -a option forces all file sys- 
tems in letclfstab to have their quotas disabled. 

These commands update the status field of devices located in /etc/mtab to indicate when quotas are on or 
off for each file system. 

FILES 

quotas quota file at the file system root 

/etc/mtab mounted file systems 

/etc/fstab default file systems 

SEE ALSO 

quotactl(2), mtab(5), fstab(5) 
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NAME 

rc - command script for auto-reboot and daemons 
SYNOPSIS 

/etc/rc 

/etc/rc.Iocal 

DESCRIPTION 

Rc is the command script which controls the automatic reboot and rc.local is the script holding commands 
which are pertinent only to a specific site. 

When an automatic reboot is in progress, rc is invoked with the argument autoboot and runs a fsck with 
option -p to “preen” all the disks of minor inconsistencies resulting from the last system shutdown and to 
check for serious inconsistencies caused by hardware or software failure. If this auto-check and repair 
succeeds, then the second part of rc is run. 

The second part of rc, which is run after a auto-reboot succeeds and also if rc is invoked when a single user 
shell terminates (see init(Z)), starts all the daemons on the system, preserves editor files and clears the 
scratch directory /tmp. Rc.local is executed immediately before any other commands after a successful 
fsck. Normally, the first commands placed in the rc.local file define the machine’s name, using host- 
name (l), and save any possible core image that might have been generated as a result of a system crash, 
savecore( 8). The latter command is included in the rc.local file because the directory in which core dumps 
are saved is usually site specific. 

SEE ALSO 

init(8), reboot(8), savecore(8) 
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NAME 

rdate - set system date from a remote host 
SYNOPSIS 

/usr/ucb/rdate hostname 
DESCRIPTION 

Rdate sets the local date and time from the hostname given as argument You must be super-user on the 
local system. Typically rdate can be inserted as part of your letc/rc.local startup script 

SEE ALSO 

timed(8C) 

BUGS 

Could be modified to accept a list of hostnames and try each until a valid date returned. Better yet would 
be to write a real date server that accepted broadcast requests. 
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NAME 

reboot - UNIX bootstrapping procedures 
SYNOPSIS 

/etc/reboot [ -n ] [ -q ] 

DESCRIPTION 

The UNIX operating system is started by placing it in memory transferring to it. Since the system is not 
re-enterable, it is necessary to read it in from disk or tape each time it is to be bootstrapped. 

Rebooting a running system. When a UNIX system is running and a reboot is desired, shutdown^ 8) is 
normally used. If there are no users then /etc/reboot can be used. Reboot performs a sync operation on the 
disks, and then a multi-user reboot (as described below) is initiated. This causes a system to be booted and 
an automatic disk check to be performed. If all this succeeds without incident, the system is then brought 
up multi-user. 

OPTIONS 

-n option avoids the sync. It can be used if a disk or the processor is on fire. 

-q reboots quickly and ungracefully, without first shutting down running processes. 

Power fail and crash recovery. Normally, the system will reboot itself at power-up or after crashes. 
When it reboots, an automatic consistency check of the file systems is done. If this check is successful, the 
system resumes multi-user operations. 

The boot program finds the corresponding file on the given device, loads that file into memory location 
zero, and starts the program at the entry address specified in the program header. Normal line editing char- 
acters can be used in specifying the pathname. 

For tapes, the minor device number gives a file offset 

FILES 

/vmunix system code 

/boot system bootstrap 

SEE ALSO 

crash(8S), fsck(8), init(8), rc(8), shutdown(8), halt(8), newfs(8) 
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NAME 

recnews - receive unprocessed articles via mail 
SYNOPSIS 

/usr/lib/news/recnews [ newsgroup [ sender ] ] 

DESCRIPTION 

Recnews reads a letter from the standard input; determines the article title, sender, and newsgroup; and 
gives the body to inews with the right arguments for insertion. 

If newsgroup is omitted, the to line of the letter is used. If sender is omitted, the sender is determined from 
the from line of the letter. The title is determined from the subject line. 

SEE ALSO 

inews(l), uurec(8), sendnews(8), readnews(l), checknews(l) 
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NAME 

renice - alter priority of running processes 
SYNOPSIS 

/etc/renice [ -g ] [ -u ] priority who ... 

DESCRIPTION 

Renice can be used to alter the scheduling priority of one or more running processes. By default, the 
processes to be affected are specified by their process id’s. If the -g option is specified, the who parame- 
ters are interpreted as process groups and all the processes in the specified process groups have their 
scheduling priority altered. If the -u option is indicated, the who parameters are interpreted as user names 
and all process owned by the user are affected. 

Users other than the super-user may only alter the priority of processes they own, and can only monotoni- 
cally increase their “nice value” within the range 0 to PRIOMIN (20). (This prevents overriding admin- 
istrative fiats.) The super-user may alter the priority of any process and set the priority to any value in the 
range PRIO_MAX (-20) to PRIO MIN. Useful priorities are: 19 (the affected processes will run only 
when nothing else in the system wants to), 0 (the “base” scheduling priority), anything negative (to make 
things go very fast). 

If no who parameter is specified, the current process (alternatively, process group or user) is used. 

FILES 

/etc/pass wd to map user names to user id’s 

SEE ALSO 

getpriority(2) 

BUGS 

If you make the priority very negative, then the process cannot be interrupted. To regain control you must 
make the priority greater than zero. Non super-users can not increase scheduling priorities of their own 
processes, even if they were the ones that decreased the priorities in the first place. 
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NAME 

repquota - summarize quotas for a file system 
SYNOPSIS 

/usr/etc/repquota [ -v ] filesys... 

/usr/etc/repquota [ -v ] -a 

DESCRIPTION 

Repquota prints a summary of the disc usage and quotas for the specified file systems. For each user the 
current number files and amount of space (in kilobytes) is printed, along with any quotas created with 
edquota(8). The -a option reports on all file systems indicated in /etc/fstab to be read-write with quotas. 
The -v option causes reporting of all quotas, even if there is no usage. 

Only the super-user may view quotas which are not their own. 

FILES 

quotas quota file at the file system root 

/etc/fstab default file systems 

SEE ALSO 

quota(l), quotactl(2), quotacheck(8), quotaon(8), edquota(8) 
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NAME 

restore - incremental file system restore 
SYNOPSIS 

/etc/restore key [ name ... ] 

DESCRIPTION 

Restore restores files from tapes previously created via the dump{ 8) command. Restore’s actions are con- 
trolled by the key argument. The key is a string of characters containing at most one function letter and 
possibly one or more function modifiers. Other arguments to restore are file or directory names specifying 
the files that are to be restored. Unless the h key is specified (see below), the appearance of a directory 
name refers to the files and (recursively) subdirectories of that directory. 

FUNCTION LETTERS 

The function portion of the key is specified by one of the following letters: 

r The tape is read and loaded into the current directory. This should not be done lightly; the r key 
should only be used to restore a complete dump tape onto a clear file system or to restore an incre- 
mental dump tape after a full level zero restore. Thus: 
tutorial% /etc/newfs /dev/rxyOg eagle 
tutorial% /etc/mount /dev/xyOg /mnt 
tutorial% cd /mnt 
tutorial% restore r 

is a typical sequence to restore a complete dump. Another restore can be done to get an incremental 
dump in on top of this. A dump{%) followed by a newfs{ 8) and a restore can be used to change the 
size of a file system. 

R Restore requests a particular tape of a multi volume set on which to restart a full restore (see the r 
key above). This allows restore to be interrupted and then restarted. 

x Extract the named files from the tape. If the named file matches a directory whose contents had been 
written onto the tape, and the h key is not specified, the directory is recursively extracted. The 
owner, modification time, and mode are restored (if possible). If no file argument is given, the root 
directory is extracted, which results in the entire content of the tape being extracted, unless the h key 
has been specified. 

t List the names of the specified files if they occur on the tape. If no file argument is given, the root 
directory is listed, which results in the entire content of the tape being listed, unless the h key has 
been specified. Note that the t key replaces the function of the old dumpdir program. 

i Restore files interactively from a dump tape. After reading in the directory information from the 
tape, restore provides a shell like interface within which the user can move around the directory tree 
selecting files to be extracted. The available commands that this ‘shell’ provides are given below. 
For those commands that require an argument, the default is the current directory. 

Is [arg] List the current or specified directory. Entries that are directories are appended with a 
7’. Entries that have been marked for extraction are prepended with a If the ver- 
bose key is set the inode number of each entry is also listed. 

cd arg Change the current working directory to the specified argument. 

pwd Print the full pathname of the current working directory. 

add [arg] Add the current directory or specified argument to the list of files to be extracted. If a 
directory is specified, add that directory and all its to the extraction list (unless the h key 
is specified on the command line). Files that are on the extraction list are prepended 
with a **’ when they are listed by Is. 

delete [arg] 

Delete the current directory or specified argument from the list of files to be extracted. 
If a directory is specified, delete that directory and all its descendents from the extraction 
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list (unless the h key is specified on the command line). The most expedient way to 
extract most of the files from a directory is to add the directory to the extraction list and 
then delete those files that are not needed. 

extract Extract from the dump tape all the files that are on the extraction list. Restore asks 
which volume the user wishes to mount. The fastest way to extract a few files is to start 
with the last volume, and work towards the first volume. 

verbose Toggle the sense of the v key. When the verbose key is set, the Is command lists the 
inode numbers of all entries, and restore also displays information about each file as it is 
extracted. 

help List a summary of the available commands. 

quit Restore immediately exits, even if the extraction list is not empty. 

FUNCTION MODIFIERS 

The function modifiers which may be used in addition to the function letters are as follows. A few of these 
modifiers — namely b, f, and s — take an argument from the command line. If you use more than one of b, 
f, and s, nest your arguments as you do your modifiers; if you use b first on file command line, place its 
argument first on the command line, and so on. 


b Specifies the blocking factor for the restore. The blocking factor is taken from the next argument on 
the command line. This corresponds to the b key in dump{ 8). 

d Turns on debugging output. 

v This is the verbose option. It means display the name of each file it treats preceded by its file type. 
Restore normally works silently. 

f Use the next argument to restore as the name of the archive instead of /dev/rmt?. If the name of the 
file is restore reads from standard input. Thus, dump( 8) and restore can be used in a pipeline to 
dump and restore a file system with the command 

tutorial% dump Of-/usr | (cd /mnt; restore xf -) 

If the name of the file is ‘machine:device’ the restore is done from the specified machine through the 
internet using rmt( 8C). 

s The next argument indicates that restore is to skip to the n'th file when there are multiple dump files 
on the dump tape. For example, a command like 
tutorial% restore xfs /dev/nrarO 5 
would position you at the fifth file on the tape. 

y Do not ask whether to abort the restore in the event of tape errors. Restore always tries to skip over 
the bad tape block(s) and continue as best it can. 

m Extract by inode numbers rather than by file name. This is useful if only a few files are being 
extracted, and one wants to avoid regenerating the complete pathname to the file. 

h Extract the actual directory, rather than the files that it references. This prevents hierarchical restora- 
tion of complete subtrees from the tape. 

c Convert the contents of the dump tape to the new file system format. 


DIAGNOSTICS 

Complaints about bad key characters. 

Complaints if it gets a read error. If y has been specified, or the user responds ‘y’> restore will attempt to 
continue the restore. 


If the dump extends over more than one tape, restore asks the user to change tapes. If the x or i key has 
been specified, restore also asks which volume the user wishes to mount. The fastest way to extract a few 
files is to start with the last volume, and work towards the first volume. 
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There are numerous consistency checks that can be listed by restore . Most checks are self-explanatory or 
can ‘never happen’. Common errors are given below. 

Converting to new file system format. 

A dump tape created from the old file system has been loaded. It is automatically converted to the 
new file system format. 

<filename>: not found on tape 

The specified file name was listed in the tape directory, but was not found on the tape. This is caused 
by tape read errors while looking for the file, and from using a dump tape created on an active file 
system. 

expected next file <inumber>, got <inumber> 

A file that was not listed in the directory showed up. This can occur when using a dump tape created 
on an active file system. 

Incremental tape too low 

When doing incremental restore, a tape that was written before the previous incremental tape, or that 
has too low an incremental level has been loaded. 


Incremental tape too high 

When doing incremental restore, a tape that does not begin its coverage where the previous incre- 
mental tape left off, or that has too high an incremental level has been loaded. 

Tape read error while restoring <filename> 

Tape read error while skipping over inode <inumber> 

Tape read error while trying to resynchronize 

A tape read error has occurred. If a file name is specified, then its contents are probably partially 
wrong. If an inode is being skipped or the tape is trying to resynchronize, then no extracted files 
have been corrupted, though files may not be found on the tape. 

resync restore, skipped <num> blocks 

After a tape read error, restore may have to resynchronize itself. This message lists the number of 
blocks that were skipped over. 


FILES 

/dev/rmt? 

/tmp/rstdir* 

/tmp/rstmode* 

,/restoresymtab 


the default tape drive 
file containing directories on the tape, 
owner, mode, and time stamps for directories, 
information passed between incremental restores. 


SEE ALSO 

dump(8), newfs(8), mount(8), mkfs(8), rmt(8C) 


BUGS 

Restore can get confused when doing incremental restores from dump tapes that were made on active file 
systems. 

A level zero dump must be done after a full restore. Because restore runs in user mode, it has no control 
over inode allocation; this means that restore re-positions the files, although it does change their contents. 
Thus, a full dump must be done to get a new set of directories reflecting the new file positions, so that later 
incremental dumps will be correct. 
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NAME 

rexecd - remote execution server 
SYNOPSIS 

/usr/etc/in.rexecd host.port 
DESCRIPTION 

Rexecd is the server for the rexec (3N) routine. The server provides remote execution facilities with 
authentication based on user names and encrypted passwords. It is invoked automatically as needed by 
inetd{ 8C), and then executes the following protocol: 

1) The server reads characters from the socket up to a null (‘\0’) byte. The resultant string is inter- 
preted as an ASCII number, base 10. 

2) If the number received in step 1 is non-zero, it is interpreted as the port number of a secondary 
stream to be used for the stderr. A second connection is then created to the specified port on the 
client’s machine. 

3) A null terminated user name of at most 16 characters is retrieved on the initial socket. 

4) A null terminated, encrypted, password of at most 16 characters is retrieved on the initial socket. 

5) A null terminated command to be passed to a shell is retrieved on the initial socket. The length of 
the command is limited by the upper bound on the size of the system’s argument list. 

6) Rexecd then validates the user as is done at login time and, if the authentication was successful, 
changes to the user’s home directory, and establishes the user and group protections of the user. If 
any of these steps fail the connection is aborted with a diagnostic message returned. 

7) A null byte is returned on the connection associated with the stderr and the command line is 
passed to the normal login shell of the user. The shell inherits the network connections esta- 
blished by rexecd. 

DIAGNOSTICS 

All diagnostic messages are returned on the connection associated with the stderr, after which any network 
connections are closed. An error is indicated by a leading byte with a value of 1 (0 is returned in step 7 
above upon successful completion of all the steps prior to the command execution). 

“username too long” 

The name is longer than 16 characters. 

“password too long” 

The password is longer than 16 characters. 

“command too long ” 

The command line passed exceeds the size of the argument list (as configured into the system). 

“Login incorrect.” 

No password file entry for the user name existed. 

“Password incorrect.” 

The wrong password was supplied. 

“No remote directory.” 

The chdir command to the home directory failed. 

“Try again.” 

A fork by the server failed. 

“/bin/sh: ...” 

The user’s login shell could not be started. 

BUGS 

Indicating “Login incorrect” as opposed to “Password incorrect” is a security breach which allows peo- 
ple to probe a system for users with null passwords. 
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A facility to allow all data exchanges to be encrypted should be present. 

SEE ALSO 

inetd(8C) 
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NAME 

rlogind - remote login server 
SYNOPSIS 

/etc/in.rlogind host.port 
DESCRIPTION 

Rlogind is the server for the rlogin( 1C) program. The server provides a remote login facility with authenti- 
cation based on privileged port numbers. 

Rlogind is invoked by inetd( 8C) when a remote login connection is established, and executes the following 
protocol: 

1) The server checks the client’s source port. If the port is not in the range 0-1023, the server aborts 
the connection. The client’s address and port number are passed as arguments to rlogind by inetd 
in the form “hostport” with host in hex and port in decimal. 

2) The server checks the client’s source address. If the address is associated with a host for which no 
corresponding entry exists in the host name data base (see hosts ( 5)), the server aborts the connec- 
tion. 

Once the source port and address have been checked, rlogind allocates a pseudo terminal (see pty(4)), and 
manipulates file descriptors so that the slave half of the pseudo terminal becomes the stdin , stdout , and 
stderr for a login process. The login process is an instance of the login(l) program, invoked with the -r 
option. The login process then proceeds with the authentication process as described in rshd( 8C), but if 
automatic authentication fails, it reprompts the user to login as one finds on a standard terminal line. 

The parent of the login process manipulates the master side of the pseudo terminal, operating as an 
intermediary between the login process and the client instance of the rlogin program. In normal operation, 
the packet protocol described in pty( 4) is invoked to provide A S/ A Q type facilities and propagate interrupt 
signals to the remote programs. The login process propagates the client terminal’s baud rate and terminal 
type, as found in the environment variable, “TERM”; see environ( 5). 

DIAGNOSTICS 

All diagnostic messages are returned on the connection associated with the stderr, after which any network 
connections are closed. An error is indicated by a leading byte with a value of 1. 

“Hostname for your address unknown.” 

No entry in the host name database existed for the client’s machine. 

“Try again.” 

A fork by the server failed. 

“/bin/sh: ...” 

The user’s login shell could not be started. 

BUGS 

The authentication procedure used here assumes the integrity of each client machine and the connecting 
medium. This is insecure, but is useful in an “open” environment. 

A facility to allow all data exchanges to be encrypted should be present. 

SEE ALSO 

inetd(8C) 
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NAME 

rmail - handle remote mail received via uucp 

SYNOPSIS 

rmail user ... 

DESCRIPTION 

Rmail interprets incoming mail received via uucp(lC), collapsing “From” lines in the form generated by 
binmail{\) into a single line of the form “retum-pathisender”, and passing the processed mail on to send- 
mail(8). 

Rmail is explicidy designed for use with uucp and sendmail. 

SEE ALSO 

binmail(l), uucp(lC), sendmail(8) 

BUGS 

Rmail should not reside in /bin. 
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NAME 

rmt - remote magtape protocol module 

SYNOPSIS 

/etc/rmt 

DESCRIPTION 

Rmt is a program used by the remote dump and restor programs in manipulating a magnetic tape drive 
through an interprocess communication connection. Rmt is normally started up with an rexec( 3N) or 
rcmd{ 3N) call. 

The rmt program accepts requests specific to the manipulation of magnetic tapes, performs the commands, 
then responds with a status indication. All responses are in ASCII and in one of two forms. Successful 
commands have responses of 

\number\n 

where number is an ASCII representation of a decimal number. Unsuccessful commands are responded to 
with 

Eerror-number\nerror-message\n, 

where error-number is one of the possible error numbers described in intro (2) and error-message is the 
corresponding error string as printed from a call to perror{ 3). The protocol is comprised of the following 
commands (a space is present between each token). 

0 device mode Open the specified device using the indicated mode . Device is a full pathname and mode 

is an ASCII representation of a decimal number suitable for passing to open (2). If a 
device had already been opened, it is closed before a new open is performed. 

C device Close the currently open device. The device specified is ignored. 

L whence offset Perform an lseek{ 2) operation using the specified parameters. The response value is that 
returned from the Iseek call. 

W count Write data onto the open device. Rmt reads count bytes from the connection, aborting if 

a premature end-of-file is encountered. The response value is that returned from the 
write (2) call. 

R count Read count bytes of data from the open device. Rmt performs the requested read (2) and 

responds with kcount-read\n if the read was successful; otherwise an error in the stan- 
dard format is returned. If the read was successful, the data read is then sent. 

1 operation count 

Perform a MTIOCOP ioctl(2) command using the specified parameters. The parameters 
are interpreted as the ASCII representations of the decimal values to place in the mt_op 
and mt_count fields of the structure used in the ioctl call. The return value is the count 
parameter when the operation is successful. 

S Return the status of the open device, as obtained with a MTIOCGET ioctl call. If the 

operation was successful, an “ack” is sent with the size of the status buffer, then the 
status buffer is sent (in binary). 

Any other command causes rmt to exit. 

DIAGNOSTICS 

All responses are of the form described above. 

SEE ALSO 

rcmd(3N), rexec(3N), mtio(4), dump(8), restore(8) 

BUGS 

People tempted to use this for a remote file access protocol are discouraged. 
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NAME 

route - manually manipulate the routing tables 

SYNOPSIS 

/usr/etc/route [ — f ] [ command, args ] 

DESCRIPTION 

Route is a program used to manually manipulate the network routing tables. It normally is not needed, as 
the system routing table management daemon, routed^ 8C), should tend to this task. 

Route accepts three commands: add, to add a route; delete, to delete a route; and change, to modify an 
existing route. 

All commands have the following syntax: 

/usr/etc/route command destination gateway [ metric ] 

where destination is a host or network for which the route is “to”, gateway is the gateway to which pack- 
ets should be addressed, and metric is an optional count indicating the number of hops to the destination. 
If no metric is specified, route assumes a value of 0. Routes to a particular host are distinguished from 
those to a network by interpreting the Internet address associated with destination. If the destination has a 
“local address part” of INADDR ANY, then the route is assumed to be to a network; otherwise, it is 
presumed to be a route to a host. If the route is to a destination connected via a gateway, the metric should 
be greater than 0. All symbolic names specified for a destination or gateway are looked up first in the host 
name database, hosts (5). If this lookup fails, the name is then looked for in the network name database, 
networks{ 5). 

Route uses a raw socket and the SIOCADDRT and SIOCDELRT ioctl’s to do its work. As such, only the 
super-user may modify the routing tables. 

If the -f option is specified, route will “flush” the routing tables of all gateway entries. If this is used in 
conjunction with one of the commands described above, the tables are flushed prior to the command’s 
application. 

DIAGNOSTICS 

“add %s: gateway %s flags %x” 

The specified route is being added to the tables. The values printed are from the routing table entry sup- 
plied in the ioctl call. 

“delete %s: gateway %s flags %x” 

As above, but when deleting an entry. 

“%s %s done” 

When the -f flag is specified, each routing table entry deleted is indicated with a message of this form. 

“not in table” 

A delete operation was attempted for an entry which wasn’t present in the tables. 

“routing table overflow” 

An add operation was attempted, but the system was low on resources and was unable to allocate memory 
to create the new entry. 

SEE ALSO 

routing(4N), routed(8C) 

BUGS 

The change operation is not implemented, one should add the new route, then delete the old one. 
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NAME 

routed - network routing daemon 
SYNOPSIS 

/etc/in.routed [ — s ] [ — q ] t — t ] [ logfile ] 

DESCRIPTION 

Routed is invoked at boot time to manage the network routing tables. The routing daemon uses a variant of 
the Xerox NS Routing Information Protocol in maintaining up to date kernel routing table entries. 

In normal operation routed listens on udp(4 P) socket 520 (decimal) for routing information packets. If the 
host is an internetwork router, it periodically supplies copies of its routing tables to any directly connected 
hosts and networks. 

When routed is started, it uses the SIOCGIFCONF ioctl to find those directly connected interfaces 
configured into the system and marked “up” (the software loopback interface is ignored). If multiple 
interfaces are present, it is assumed the host will forward packets between networks. Routed then transmits 
a request packet on each interface (using a broadcast packet if the interface supports it) and enters a loop, 
listening for request and response packets from other hosts. 

When a request packet is received, routed formulates a reply based on the information maintained in its 
internal tables. The response packet generated contains a list of known routes, each marked with a “hop 
count” metric (a count of 16, or greater, is considered “infinite”). The metric associated with each route 
returned provides a metric relative to the sender. 

Request packets received by routed are used to update the routing tables if one of the following conditions 
is satisfied: 

(1) No routing table entry exists for the destination network or host, and the metric indicates the desti- 
nation is “reachable” (that is, the hop count is not infinite). 

(2) The source host of the packet is the same as the router in the existing routing table entry. That is, 
updated information is being received from the very internetwork router through which packets 
for the destination are being routed. 

(3) The existing entry in the routing table has not been updated for some time (defined to be 90 
seconds) and the route is at least as cost effective as the current route. 

(4) The new route describes a shorter route to the destination than the one currently stored in the rout- 
ing tables; the metric of the new route is compared against the one stored in the table to decide 
this. 

When an update is applied, routed records the change in its internal tables and generates a response packet 
to all directly connected hosts and networks. Routed waits a short period of time (no more than 30 
seconds) before modifying the kernel’s routing tables to allow possible unstable situations to settle. 

In addition to processing incoming packets, routed also periodically checks the routing table entries. If an 
entry has not been updated for 3 minutes, the entry’s metric is set to infinity and marked for deletion. Dele- 
tions are delayed an additional 60 seconds to insure the invalidation is propagated throughout the internet. 

Hosts acting as internetwork routers gratuitously supply their routing tables every 30 seconds to all directly 
connected hosts and networks. 

Supplying the -s option forces routed to supply routing information whether it is acting as an internetwork 
router or not. The -q option is the opposite of the -s option. If the -t option is specified, all packets sent 
or received are printed on the standard output In addition, routed will not divorce itself from the control- 
ling terminal so that interrupts from the keyboard will kill the process. Any other argument supplied is 
interpreted as the name of file in which routed’ s actions should be logged. This log contains information 
about any changes to the routing tables and a history of recent messages sent and received which are 
related to the changed route. 
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In addition to the facilities described above, routed supports the notion of “distant” passive and active 
gateways. When routed is started up, it reads the file /etc/ gateways to find gateways which may not be 
identified using the SIOGIFCONF ioctl. Gateways specified in this manner should be marked passive if 
they are not expected to exchange routing information, while gateways marked active should be willing to 
exchange routing information (that is, they should have a routed process running on the machine). Passive 
gateways are maintained in the routing tables forever and information regarding their existence is included 
in any routing information transmitted. Active gateways are treated equally to network interfaces. Routing 
information is distributed to the gateway and if no routing information is received for a period of the time, 
the associated route is deleted. 

The /etc/ gateways is comprised of a series of lines, each in the following format: 

< net | host > namel gateway name2 metric value < passive | active > 

The net or host keyword indicates if the route is to a network or specific host. 

Namel is the name of the destination network or host. This may be a symbolic name located in 
/etc/networks or letclhosts, or an Internet address specified in “dot” notation; see inef (3N). 

Namel is the name or address of the gateway to which messages should be forwarded. 

Value is a metric indicating the hop count to the destination host or network. 

The keyword passive or active indicates if the gateway should be treated as passive or active (as described 
above). 

FILES 

/etc/gateways for distant gateways 
SEE ALSO 

Internet Transport Protocols, XSIS 028112, Xerox System Integration Standard. (Sun 800-1066-01) 
udp(4P) 

BUGS 

The kernel’s routing tables may not correspond to those of routed for short periods of time while processes 
utilizing existing routes exit; the only remedy for this is to place the routing process in the kernel. 

Routed should listen to intelligent interfaces, such as an IMP, and to error protocols, such as ICMP, to 
gather more information. 
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NAME 

rpcinfo - report RPC information 

SYNOPSIS 

rpcinfo -p [ host ] 

rpcinfo -u host program-number [ version-number ] 
rpcinfo -t host program-number [ version-number ] 

DESCRIPTION 

Rpcinfo makes an RPC call to an RPC server and reports what it finds. 

OPTIONS 

-p Probe the portmapper on host, and print a list of all registered RPC programs. If host is not 
specified, it defaults to the value returned by hostname^ 1). 

-u Make an RPC call to procedure 0 of program-number using UDP, and report whether a response 
was received. 

— t Make an RPC call to procedure 0 of program-number using TCP, and report whether a response 
was received. 

The program-number argument can be either a name or a number. If no version is given, it defaults to 1. 

FILES 

/etc/rpc names for rpc program numbers 
SEE ALSO 

RPC Programming Guide, rpc(5), portmap(8) 
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NAME 

rquotad - remote quota server 

SYNOPSIS 

/usr/etc/rpc.rquotad 

DESCRIPTION 

Rquotad is an rpc( 4) server which returns quotas for a user of a local file system which is mounted by a 
remote machine over the NFS. The results are used by quota{ 1) to display user quotas for remote file sys- 
tems. The rquotad daemon is normally invoked by inetd(SC). 

FILES 

quotas quota file at the file system root 

SEE ALSO 

quota(l), services(5), inetd(8), rpc(4), nfs(4) 
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NAME 

rshd - remote shell server 

SYNOPSIS 

/etc/in.rshd host.port 

DESCRIPTION 

Rshd is the server for the rcmd( 3N) routine and, consequently, for the rsh( 1C) program. The server pro- 
vides remote execution facilities with authentication based on privileged port numbers. 

Rshd is invoked by inetd( 8C) each time a shell service is requested, and executes the following protocol: 

1) The server checks the client’s source port. If the port is not in the range 0-1023, the server aborts 
the connection. The clients host address (in hex) and port number (in decimal) are the argument 
passed to rshd. 

2) The server reads characters from the socket up to a null (‘\0’) byte. The resultant string is inter- 
preted as an ASCII number, base 10. 

3) If the number received in step 1 is non-zero, it is interpreted as the port number of a secondary 
stream to be used for the stderr. A second connection is then created to the specified port on the 
client’s machine. The source port of this second connection is also in the range 0-1023. 

4) The server checks the client’s source address. If the address is associated with a host for which no 
corresponding entry exists in the host name data base (see hosts (5)), the server aborts the connec- 
tion. 

5) A null terminated user name of at most 16 characters is retrieved on the initial socket. This user 
name is interpreted as a user identity to use on the server’s machine. 

6) A null terminated user name of at most 16 characters is retrieved on the initial socket. This user 
name is interpreted as the user identity on the client’s machine. 

7) A null terminated command to be passed to a shell is retrieved on the initial socket. The length of 
the command is limited by the upper bound on the size of the system’s argument list. 

8) Rshd then validates the user according to the following steps. The remote user name is looked up 
in the password file and a chdir is performed to the user’s home directory. If the lookup or fails, 
the connection is terminated. If the chdir fails, it does a chdir to / (root). If the user is not the 
super-user, (user id 0), the file letclhosts.equiv is consulted for a list of hosts considered 
“equivalent”. If the client’s host name is present in this file, the authentication is considered suc- 
cessful. If the lookup fails, or the user is the super-user, then the file .rhosts in the home directory 
of the remote user is checked for the machine name and identity of the user on the client’s 
machine. If this lookup fails, the connection is terminated. 

9) A null byte is returned on the connection associated with the stderr and the command line is 
passed to the normal login shell of the user. The shell inherits the network connections esta- 
blished by rshd. 

DIAGNOSTICS 

All diagnostic messages are returned on the connection associated with the stderr, after which any network 
connections are closed. An error is indicated by a leading byte with a value of 1 (0 is returned in step 9 
above upon successful completion of all the steps prior to the command execution). 

“locuser too long” 

The name of the user on the client’s machine is longer than 16 characters. 

“remuser too long” 

The name of the user on the remote machine is longer than 16 characters. 

“command too long ” 

The command line passed exceeds the size of the argument list (as configured into the system). 
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“Hostname for your address unknown.” 

No entry in the host name database existed for the client’s machine. 

“Login incorrect.” 

No password file entry for the user name existed. 

“Permission denied.” 

The authentication procedure described above failed. 

“Can’t make pipe.” 

The pipe needed for the stderr, wasn’t created. 

“Try again.” 

A fork by the server failed. 

“/bin/sh: ...” 

The user’s login shell could not be started. 

SEE ALSO 

rsh(lC), rcmd(3N) 

BUGS 

The authentication procedure used here assumes the integrity of each client machine and the connecting 
medium. This is insecure, but is useful in an “open” environment. 

A facility to allow all data exchanges to be encrypted should be present 
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NAME 

rstatd - kernel statistics server 

SYNOPSIS 

/usr/etc/rpc.rstatd 

DESCRIPTION 

Rstatd is a server which returns performance statistics obtained from the kernel. These statistics are graph- 
ically displayed by perf meter (l). The rstatd daemon is normally invoked by inetd(SC). 

SEE ALSO 

perfmeter(l), services(5), inetd(8) 
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NAME 

rwalld - network rwall server 

SYNOPSIS 

/usr/etc/rpc.rwalld 

DESCRIPTION 

Rwalld is a server that handles rwall{ 1) and shutdown(l) requests. It is implemented by calling wall( 1) to 
all the appropriate network machines. The rwalld daemon is normally invoked by inetd( 8C). 

SEE ALSO 

rwall(l), wall(l), services(5), inetd(8), shutdown(8) 
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NAME 

rwhod - system status server 

SYNOPSIS 

/etc/rwhod 

DESCRIPTION 

Rwhod is the server which maintains the database used by the rwho( 1C) and ruptime(\C) programs. Its 
operation is predicated on the ability to broadcast messages on a network. 

Rwhod operates as both a producer and consumer of status information. As a producer of information it 
periodically queries the state of the system and constructs status messages which are broadcast on a net- 
work. As a consumer of information, it listens for other rwhod servers’ status messages, validating them, 
then recording them in a collection of files located in the directory lusrlspool/rwho. 

The rwho server transmits and receives messages at the port indicated in the “rwho” service specification, 
see services (5). The messages sent and received, are of the form: 

struct outmp { 

char out_line[8]; /* tty name*/ 

char out_name[8]; /* user id*/ 

long out_time; /* time on */ 

}; 

struct whod { 

char wd_vers; 

char wdtype; 

char wd_fill[2]; 

int wdsendtime; 

int wdrecvtime; 

char wd_hostname[32]; 
int wd_loadav[3]; 

int wd_boottime; 

struct whoent { 

struct outmp weutmp; 

int weidle; 

} wd_we[1024 / sizeof (struct whoent)]; 

}; 

All fields are converted to network byte order prior to transmission. The load averages are as calculated by 
the w(l) program, and represent load averages over the 5, 10, and 15 minute intervals prior to a server’s 
transmission. The host name included is that returned by the gethostname (2) system call. The array at the 
end of the message contains information about the users logged in to the sending machine. This informa- 
tion includes the contents of the utmp{ 5) entry for each non-idle terminal line and a value indicating the 
time since a character was last received on the terminal line. 

Messages received by the rwho server are discarded unless they originated at a rwho server’s port. In addi- 
tion, if the host’s name, as specified in the message, contains any unprintable ASCII characters, the mes- 
sage is discarded. Valid messages received by rwhod are placed in files named whod. hostname in the 
directory lusrlspool/rwho. These files contain only the most recent message, in the format described 
above. 

Status messages are generated approximately once every 60 seconds. Rwhod performs an nlist( 3) on 
/vmunix every 10 minutes to guard against the possibility that this file is not the system image currently 
operating. 

SEE ALSO 

rwho(lC), ruptime(lC) 
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BUGS 

Should relay status information between networks. People often interpret the server dying as a machine 
going down. 
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NAME 

sa, accton - system accounting 
SYNOPSIS 

/usr/etc/sa [ -abcdDfijkKlnrstuv ] [ file ] 

/usr/etc/accton [ file ] 

DESCRIPTION 

With an argument naming an existing file, accton causes system accounting information for every process 
executed to be placed at the end of the file. If no argument is given, accounting is turned off. 

sa reports on, cleans up, and generally maintains accounting files. 

sa is able to condense the information in lusr/adm/acct into a summary file lusrladmlsavacct which con- 
tains a count of the number of times each command was called and the time resources consumed. This 
condensation is desirable because on a large system lusr/adm/acct can grow by 500K bytes per day. The 
summary file is normally read before the accounting file, so the reports include all available information. 

If a file name is given as the last argument, that file will be treated as the accounting file; lusrladmlacct is 
the default 

Output fields are labelled: ‘cpu’ for the sum of user+system time (in minutes), ‘re’ for real time (also in 
minutes), ‘k’ for cpu-time averaged core usage (in lk units), ‘avio’ for average number of I/O operations 
per execution. With options fields labelled ‘tio’ for total I/O operations, ‘k*sec’ for cpu storage integral 
(kilo-core seconds), ‘u’ and ‘s’ for user and system cpu time alone (both in minutes) will sometimes 
appear. 

sa also breaks out accounting statistics by user. This information is kept in the file lusrladmlusracct. 
OPTIONS 

a Place all command names containing unprintable characters and those used only once under the 
name ‘***other.’ 

b Sort output by sum of user and system time divided by number of calls. Default sort is by sum of 
user and system times. 

c Besides total user, system, and real time for each command print percentage of total time over all 
commands. 

d Sort by average number of disk I/O operations. 

D Print and sort by total number of disk I/O operations, 
f Force no interactive threshold compression with -v flag, 
i Don’t read in summary file. 

j Instead of total minutes time for each category, give seconds per call, 

k Sort by cpu-time average memory usage. 

K Print and sort by cpu-storage integral. 

1 Separate system and user time; normally they are combined, 

m Print number of processes and number of CPU minutes for each user, 
n Sort by number of calls, 

r Reverse order of sort. 

s Merge accounting file into summary file lusrladmlsavacct when done. 

t For each command report ratio of real time to the sum of user and system times. 

u Superseding all other flags, print for each record in the accounting file the user ID and command 

name. 
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v Followed by a number n, types the name of each command used n times or fewer. Await a reply 
from the terminal; if it begins with ‘y\ add the command to the category ‘**junk**.’ This is used 
to strip out garbage. 

FILES 

/usr/adm/acct raw accounting /usr/adm/savacct summary by com- 
mand /usr/adm/usracct summary by userid 

SEE ALSO 

ac(8), acct(2), acct(5) 
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NAME 

savecore - save a core dump of the operating system 
SYNOPSIS 

/usr/etc/savecore dirname [ system ] 

DESCRIPTION 

Savecore is meant to be called near the end of the letclrc file after the system boots. Savecore ’s function is 
to save the core dump of the system (assuming one was made) and to write a reboot message in the shut- 
down log. 

Savecore checks the core dump to be certain it corresponds with the current running version of the operat- 
ing system. If it does, savecore saves the core image in the file dirname /vmcoTe.n and its brother, the 
namelist, dirname Nmamx.n The trailing .n in the pathnames is replaced by a number which grows every 
time savecore is run in that directory. 

Before savecore writes out a core image, it reads a number from the file dirname /minfree. If there less free 
space on the filesystem which contains dirname than the number obtained from the minfree file, the core 
dump is not done. If the minfree file does not exist, savecore always writes out the core file (assuming that 
a core dump was taken). 

Savecore also writes a reboot message in the shut down log. If the system crashed as a result of a panic, 
savecore records the panic string in the shut down log too. 

If the core dump was from a system other than /vmunix, the name of that system must be supplied as 
sysname. 

FILES 

/usr/adm/shutdownlog shut down log 

/usr2/crash/‘hostname‘/bounds number to assign to the core images 
/vmunix current UNIX 

BUGS 

Can be fooled into thinking a core dump is the wrong size. 
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NAME 

sendmail - send mail over the internet 
SYNOPSIS 

/usr/lib/sendmail [ -ba ] [ -bd ] [ -bi ] [ -bm ] [ -bp ] [ -bs ] [ -bt ] [ -bv ] [ -bz ] 

[ -C file ] [ -dX ] [ — F fullname ] [ -f name ] [ -h N ] [ -n ] [ -ox value ] [ -q[ time ] ] 

[ -r name ] t -t ] [ -v ] [ address . . . ] 

DESCRIPTION 

Sendmail sends a message to one or more people, routing the message over whatever networks are neces- 
sary. Sendmail does internetwork forwarding as necessary to deliver the message to the correct place. 

Sendmail is not intended as a user interface routine; other programs provide user-friendly front ends; send- 
mail is used only to deliver pre-formatted messages. 


With no flags, sendmail reads its standard input up to a control-D or a line with a single dot and sends a 
copy of the letter found there to all of the addresses listed. It determines the network to use based on the 
syntax and contents of the addresses. 

Local addresses are looked up in a file and aliased appropriately. Aliasing can be prevented by preceding 
the address with a backslash. Normally the sender is not included in any alias expansions, for example, if 
‘john’ sends to ‘group’, and ‘group’ includes ‘john’ in the expansion, then the letter will not be delivered to 

‘john’. 


OPTIONS 


-ba 

Go into ARPANET mode. All input lines must end with a CR-LF, and all messages 
will be generated with a CR-LF at the end. Also, the “From:” and “Sender:” fields 
are examined for the name of the sender. 

-bd 

Run as a daemon, waiting for incoming SMTP connections. 

-bi 

Initialize the alias database. 

-bm 

Deliver mail in the usual way (default). 

-bp 

Print a summary of the mail queue. 

-bs 

Use the SMTP protocol as described in RFC821. This flag implies all the operations of 
the -ba flag that are compatible with SMTP. 

-bt 

Run in address test mode. This mode reads addresses and shows the steps in parsing; 
it is used for debugging configuration tables. 

-bv 

Verify names only - do not try to collect or deliver a message. Verily mode is nor- 
mally used for validating users or mailing lists. 

-bz 

Create the configuration freeze file. 

-C file 

Use alternate configuration file. 

-dX 

Set debugging value to X. 

—Ffullname 

Set the full name of the sender. 

—f name 

Sets the name of the “from” person (that is, the sender of the mail), -f can only be 
used by “trusted” users (who are listed in the config file). 

-h N 

Set the hop count to N. The hop count is incremented every time the mail is pro- 
cessed. When it reaches a limit, the mail is returned with an error message, the victim 


of an aliasing loop. 

-Mid 

Attempt to deliver the queued message with message-id id. 

-n 

Don’t do aliasing. 

—ox value 

Set option x to the specified value. Options are described below. 
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-q[ time ] Processed saved messages in the queue at given intervals. If time is omitted, process 

the queue once. Time is given as a tagged number, with ‘s’ being seconds, ‘m’ being 
minutes, ‘h’ being hours, ‘d’ being days, and ‘w’ being weeks. For example, 
“-qlh30m” or “-q90m” would both set the timeout to one hour thirty minutes. 

-tname An alternate and obsolete form of the -f flag. 

-R string Go through the queue of pending mail and attempt to deliver any message with a reci- 

pient containing the specified string. This is useful for clearing out mail directed to a 
machine which has been down for awhile. 

-t Read message for recipients. To:, Cc:, and Bcc: lines will be scanned for people to 

send to. The Bcc: line will be deleted before transmission. Any addresses in the 
argument list will be suppressed. 

-v Go into verbose mode. Alias expansions will be announced, etc. 

PROCESSING OPTIONS 

There are also a number of processing options that may be set. Normally these will only be used by a sys- 
tem administrator. Options may be set either on the command line using the -o flag or in the configuration 
file. These are described in detail in the Installation and Operation Guide . The options are: 

A file Use alternate alias file. 

c On mailers that are considered “expensive” to connect to, don’t initiate immediate 

connection. This requires queueing. 

dx Set the delivery mode to x. Delivery modes are ‘i’ for interactive (synchronous) 

delivery, ‘b’ for background (asynchronous) delivery, and ‘q’ for queue only - that is, 
actual delivery is done the next time the queue is run. 

D Try to automatically rebuild the alias database if necessary. 

ex Set error processing to mode x. Valid modes are ‘m’ to mail back the error message, 

‘w’ to “write” back the error message (or mail it back if the sender is not logged in), 
‘p’ to print the errors on the terminal (default), ‘q’ to throw away error messages 
(only exit status is returned), and ‘e’ to do special processing for the BerkNet. If the 
text of the message is not mailed back by modes ‘m’ or ‘w’ and if the sender is local 
to this machine, a copy of the message is appended to the file “dead.letter” in the 
sender’s home directory. 

F mode The mode to use when creating temporary files, 

f Save UNIX-style From lines at the front of messages, 

g N The default group id to use when calling mailers. 

H file The SMTP help file. 

i Do not take dots on a line by themselves as a message terminator. 

L n The log level. 

m Send to “me” (the sender) also if I am in an alias expansion. 

o If set, this message may have old style headers. If not set, this message is guaranteed 

to have new style headers (that is, commas instead of spaces between addresses). If 
set, an adaptive algorithm is used that will correctly determine the header format in 
most cases. 

Qqueuedir Select the directory in which to queue messages. 

xtimeout The timeout on reads; if none is set, sendmail will wait forever for a mailer. 

S fie Save statistics in the named file. 

s Always instantiate the queue file, even under circumstances where it is not strictly 
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necessary. 


T time 

Set the timeout on messages in the queue to the specified time. After sitting in the 
queue for this amount of time, they will be returned to the sender. The default is 


three days. 

tstz.dtz 

Set the name of the time zone. 

u N 

Set the default user id for mailers. 

If the first character of the user name is a vertical bar, the rest of the user name is used as the name of a 
program to pipe the mail to. It may be necessary to quote the name of the user to keep sendmail from 
suppressing the blanks from between arguments. 

Sendmail returns an 

exit status describing what it did. The codes are defined in <sysexits.h> 

EX OK 

Successful completion on all addresses. 

EXNOUSER 

User name not recognized. 

EX UNAVAILABLE Catchall meaning necessary resources were not available. 

EX_SYNTAX 

Syntax error in address. 


EX SOFTWARE Internal software error, including bad arguments. 

EX OSERR Temporary operating system error, such as “cannot fork’ ’ . 

EX_NOHOST Host name not recognized. 

EX TEMPFAIL Message could not be sent immediately, but was queued. 

If invoked as newaliases, sendmail rebuilds the alias database. If invoked as mailq, sendmail prints the 
contents of the mail queue. 

FILES 

Except for /usr/lib/sendmail.cf, these pathnames are all specified in / usr/libl sendmail. cf. Thus, these values 
are only approximations. 


/usr/lib/aliases 

/usr/lib/aliases.pag 

/usr/lib/aliases.dir 

/usr/lib/sendmail.cf 

/usr/lib/sendmail.fc 

/usr/lib/sendmail.hf 

/usr/lib/sendmail.st 

/usr/bin/uux 

/bin/mail 

/usr/spool/mqueue/* 


raw data for alias names 

data base of alias names 
configuration file 
frozen configuration 
help file 

collected statistics 
to deliver uucp mail 
to deliver local mail 
temp files and queued mail 


SEE ALSO 

biff(l), binmail(l), mail(l), aliases(5), 

DARPA Internet Request For Comments RFC819, RFC821, RFC822, 

In the System Manager’s Manual : 

Setting Up the Mail System in the System Set-up and Operation chapter. 
Sendmail — An Internetwork Mail Router, in the Tutorials section 
Sendmail Installation and Operation Guide, in the Tutorials section 


BUGS 

Sendmail converts blanks in addresses to dots. This is incorrect according to the old ARPANET mail proto- 
col RFC733 (NIC 41952), but is consistent with the new protocols (RFC822). 
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NAME 

sendnews - send news articles via mail 
SYNOPSIS 

sendnews [ — o ] [ —a ] [ — b ] [ — n newsgroups ] destination 
DESCRIPTION 

sendnews reads an article from it’s standard input, performs a set of changes to it, and gives it to the mail 
program to mail it to destination. 

An ‘N’ is prepended to each line for decoding by uurec(l). 

OPTIONS 

-o handle old format articles. 

-a used for sending articles via the ARPANET. It maps the article’s path from uucphostlxxx to 
xxx@arpahost. 

-b used for sending articles via the Berknet. It maps the article’s path from uucphostlxxx to 
berkhostixxx. 

-n change the article’s newsgroup to the specified newsgroup. 

SEE ALSO 

inews(l), uurec(8), recnews(8), readnews(l), checknews(l) 
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NAME 

showmount - show all remote mounts 
SYNOPSIS 

/usr/etc/showmount [ —a ] [ — d ] [ — e ] [ host ] 

DESCRIPTION 

Showmount lists all the clients that have remotely mounted a filesystem from host. This information is 
maintained by the mountd{ 8c) server on host, and is saved across crashes in the file letclrmtab. The 
default value for host is the value returned by hostname (1). 

OPTIONS 

-d List directories that have been remotely mounted by clients. 

-a Print all remote mounts in the format 
hostname:directory 

where hostname is the name of the client, and directory is the root of the file system that has been 
mounted. 

-e Print the list of exported file systems. 

SEE ALSO 

rmtab(5), mountd(8), exports(5) 

BUGS 

If a client crashes, its entry will not be removed from the list until it reboots and executes umount -a. 
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NAME 

shutdown - close down the system at a given time 
SYNOPSIS 

/etc/shutdown [ — k ] [ — r ] [ — h ] time [ warning-message ... ] 

DESCRIPTION 

Shutdown provides an automated shutdown procedure for the super-user to notify users politely when the 
system is shutting down. Time specifies when shutdown will bring the system down; it may be the word 
now (indicating an immediate shutdown), or it may specify a future time in one of two formats: +number 
and hour \min. The first form brings the system down in number minutes, and the second brings the system 
down at the time of day indicated in 24-hour notation. 

At intervals that get closer as the apocalypse approaches, warning messages are displayed at terminals of 
all logged-in users, and of users who have remote mounts on that machine. Five minutes before shutdown, 
or immediately if shutdown is in less than 5 minutes, logins are disabled by creating letc/nologin and writ- 
ing a message there. If this file exists when a user attempts to log in, login( 1) prints its contents and exits. 
The file is removed just before shutdown exits. 

At shutdown time a message is written in the file lusrladmlshutdownlog, containing the time of shutdown, 
the instigator of the shutdown, and the reason. Then a terminate signal is sent to init, which brings the sys- 
tem down to single-user mode. 

The time of the shutdown and the warning message are placed in letc/nologin, which should be used to 
inform the users as to when the system will be back up, and why it is going down (or anything else). 

OPTIONS 

As an alternative to the above procedure, these options can be specified: 

-r Execute reboot^ 8). 

-h Execute halt( 8). 

-k Make people think the system is going down, but do not actually take it down. 

FILES 

/etc/nologin tells login not to let anyone log in 
/etc/rmtab list of remote hosts that have mounted this host 
/usr/adm/shutdownlog log file for succesful shutdowns. 

SEE ALSO 

login(l), reboot(8) 

BUGS 

Only allows you to kill the system between now and 23:59 if you use the absolute time for shutdown. 
@(#)skyversion.8 1.3 85/04/05 SMI 
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NAME 

skyversion - print the SKYFFP board microcode version number 
SYNOPSIS 

/usr/etc/skyversion 

DESCRIPTION 

skyversion obtains from the SKYFFP board the Sky version number of the microcode currently loaded and 
prints the result on the standard output. 

DIAGNOSTICS 

The Sky version number operation code used to implement this command is not available for microcode 
releases earlier than Sky release 3.00. The result in this case is unpredictable and is either a nonmeaningful 
version number or a message indicating that no version number is available. Meaningful version numbers 
are of the form n.dd where n > 3. 
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NAME 

spray - spray packets 
SYNOPSIS 

/usr/etc/spray host [ -1 lnth ] [ -c cnt ] 

DESCRIPTION 

Spray sends a one-way stream of packets to host using rpc, and then reports how many were received by 
host and what the transfer rate was. The default value of lnth is 86 bytes (the size of the rpc and udp 
headers), and the default value of cnt is the numbers of packets required to make the total stream size 
100000 bytes. The host name can be either a name or an internet address. 

The lnth parameter is the numbers of bytes in the ethemet packet that holds the rpc call message. Since the 
data is encoded using xdr, and xdr only deals with 32 bit quantities, not all values of lnth are possible. 
Spray will round up to the nearest possible value. When lnth is greater than 1514, then the rpc call can no 
longer be encapsulated in one ethemet packet, so the lnth field no longer has a simple correspondence to 
ethemet packet size. 

SEE ALSO 

rpc.sprayd(8) 


Sun Release 3.0 


Last change: 21 December 1985 


613 



SPRAYD(8C) 


MAINTENANCE COMMANDS 


SPRAYD(BC) 


NAME 

sprayd - spray server 
SYNOPSIS 

/usr/etc/r pc. sprayd 
DESCRIPTION 

Sprayd is a server which records the packets sent by spray (l). The sprayd daemon is normally invoked by 
inetd{ 8C). 

SEE ALSO 

spray(8) 
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NAME 

sticky - executable files with persistent text 
DESCRIPTION 

While the ‘sticky bit’, mode 01000 (see chmod{ 2)), is set on a sharable executable file, the text of that file 
will not be removed from the system swap area. Thus the file does not have to be fetched from the file sys- 
tem upon each execution. As long as a copy remains in the swap area, the original text cannot be overwrit- 
ten in the file system, nor can the file be deleted. Directory entries can be removed so long as one link 
remains. 

Sharable files are made by the -z option of ld( 1). 

To replace a sticky file that has been used do: (1) Clear the sticky bit with chmod(l). (2) Execute the old 
program to flush the swapped copy. This can be done safely even if others are using it. (3) Overwrite the 
sticky file. If the file is being executed by any process, writing will be prevented; it suffices to simply 
remove the file and then rewrite it, being careful to reset the owner and mode with chmod and chown(2). 
(4) Set the sticky bit again. 

Only the super-user can set the sticky bit. 
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NAME 

swapon - specify additional device for paging and swapping 

SYNOPSIS 

/usr/etc/swapon -a 
/usr/etc/swapon name ... 

DESCRIPTION 

Swapon specifies additional devices on which paging and swapping are to take place. The system begins 
by swapping and paging on only a single device so that only one disk is required at bootstrap time. Calls to 
swapon normally occur in the system multi-user initialization file letclrc making all swap devices available, 
so that the paging and swapping activity is interleaved across several devices. 

The second form gives individual block devices as given in the system swap configuration table. The call 
makes only this space available to the system for swap allocation. 

OPTIONS 

-a Make available all devices of type ‘swap’ in /etc/fstab. Using swapon with the -a option is the 
normal usage. 

SEE ALSO 

swapon(2), init(8) 

FILES 

/dev/[ru] [pk] ?b normal paging devices 

BUGS 

There is no way to stop paging and swapping on a device. It is therefore not possible to make use of dev- 
ices which may be dismounted during system operation. 
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NAME 

sync - update the super block 

SYNOPSIS 

sync 

DESCRIPTION 

Sync executes the sync system primitive. Sync can be called to insure all disk writes have been completed 
before the processor is halted in a way not suitably done by reboot (8) or halt( 8). 

See sync (2) for details on the system primitive. 

SEE ALSO 

sync(2), fsync(2), halt(8), reboot(8) 
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NAME 

sysdiag - system diagnostics 
SYNOPSIS 

/ usr/diag/sysdiag/sysdiag 
DESCRIPTION 

Sysdiag is a general-purpose system diagnostic facility that tests the system and reports its findings. It con- 
centrates on three areas of system functionality; memory, peripherals and disk. 

To use sysdiag, log on as sysdiag, then enter the command sysdiag. 

Sysdiag creates a Suntools environment with one window each for memory, peripherals, and disk error 
messages, plus a window for the console. It also creates date/time and performance monitor graphs. It 
places abbreviated error messages from the memory, disk, and peripherals in the appropriate windows, and 
sends console messages to the console window. 

When called from a terminal sysdiag interleaves all its messages on the screen. 

With or without the windows, it places long error messages in files named \ogjcx.nn where: 
xx is the name of diagnostic 
nn is the pass number (increments each pass) 

After it completes its test, sysdiag displays the error log files by executing the command more log*. These 
files remain after sysdiag exits. 

Sysdiag consists of a user account with a home directory, a collection of scripts, and executable files con- 
taining the actual test code. 

To configure or change sysdiag, either change the shell commands in /usr/diag/sysdiag/sysdiag, or change 
the sysdiag user configuration files .login, .suntools, and .cshrc. 

SEE ALSO 

Sun-2/ 160 Diagnostics Manual and Sun-2! 120 Diagnostics Manual . 
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SYSL0G(8) 


MAINTENANCE COMMANDS 


SYSLOG(8) 


NAME 

syslog - log systems messages 
SYNOPSIS 

/usr/etc/in.syslog [ -m N ] [ -{name ] [ -d ] [ -p port ] 

DESCRIPTION 

Syslog reads a datagram socket and logs each message it reads into a set of files described by the 
configuration file letclsyslog.conf. Syslog configures when it starts up and whenever it receives a hangup 
signal. Syslog logs to the host specified by ‘loghost’ in the letclhosts file. For details on running syslog in a 
Sun network environment, see the section, “System Log Configuration” in the System Set-up and Opera- 
tion chapter of the System Installation and Maintenance Guide. 

Each message logged consists of one line. A message can contain a priority code, marked by a digit in 
angle braces at the beginning of the line. Priorities are defined in <syslog.h>, as defined in the list below. 
LOG ALERT is prioity 1 (the highest priority) while LOG DEBUG is priority 9 (the lowest priority). 

LOG_ALERT this priority should essentially never be used. It applies only to messages that are so 
important that every user should be aware of them, for example, a serious hardware 
failure. 


LOG_SALERT 

LOG_EMERG 

LOGERR 

LOGCRIT 


messages of this priority should be issued only when immediate attention is needed by 
a qualified system person, for example, when some valuable system resource disap- 
pears. They get sent to a list of system people. 

Emergency messages are not sent to users, but represent major conditions. An exam- 
ple might be hard disk failures. These could be logged in a separate file so that critical 
conditions could be easily scanned. 

these represent error conditions, such as soft disk failures, etc. 

such messages contain critical information, but which can not be classed as errors, for 
example, ‘su’ attempts. Messages of this priority and higher are typically logged on 
the system console. 


LOG_WARNING 

LOG_NOTICE 

LOGJNFO 

LOGDEBUG 


issued when an abnormal condition has been detected, but recovery can take place. 

something that falls in the class of “important information;” this class is informa- 
tional but important enough that you don’t want to throw items in it away casually. 
Messages without any priority assigned to them are typically mapped into this priority. 

information level messages. These messages could be thrown away without prob- 
lems, but should be included if you want to keep a close watch on your system. 

it may be useful to log certain debugging information. Normally this will be thrown 
away. 


It is expected that the kernel will not log anything below LOG_ERR priority. 

The syslog configuration file, etclsyslog.conf, consists of two sections separated by a blank line. The first 
section defines files that syslog will log into. Each line contains a single digit which defines the lowest 
priority (highest numbered priority) that this file will receive, an optional asterisk which guarantees that 
something gets output at least every 20 minutes, and a pathname. The second part of the file contains a list 
of users that will be informed on SALERT level messages. For example, the configuration file: 


5*/dev/tty8 

8/usr/spool/adm/syslog 

3/usr/adm/critical 


eric 

kridle 

kalash 
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SYSL0G(8) 


MAINTENANCE COMMANDS 


SYSLOG(8) 


logs all messages of priority 5 or higher onto the system console, including timing marks every 20 minutes; 
all messages of priority 8 or higher into the file / usr! spooll adml syslog ; and all messages of priority 3 or 
higher into / usrladm/ critical. The users ‘eric’, ‘kridle’, and ‘kalash’ will be informed on any subalert mes- 
sages. 

OPTIONS 

-m N Set the mark interval to N (default 20 minutes). 

-f name Specify an alternate configuration file. 

-d Turn on debugging (if compiled in). 

-p port Port number where syslog listens for incoming datagrams. The default port is defined in the 
‘syslog/udp’ entry in the / etc! services file. 

To bring syslog down, it should be sent a terminate signal. It logs that it is going down and then waits 
approximately 10 seconds for any additional messages to come in. 

There are some special messages that cause control functions. ‘<*>N’ sets the default message priority to 
N. *<$>’ causes syslog to reconfigure (equivalent to a hangup signal). This can be used in a shell file run 
automatically early in the morning to truncate the log. 

Syslog creates the file /etc/syslog.pid if possible containing a single line with its process id. This can be 
used to kill or reconfigure syslog. 

FILES 

/etc/hosts - the hosts file 

/etc/syslog.conf - the configuration file 

/etc/syslog.pid - the process id 

/etc/services - to find the syslog server’s port number. 

BUGS 

LOG ALERT and LOG_SALERT messages should only be allowed to privileged programs. 

Actually, syslog is not clever enough to deal with kernel error messages in the current implementation. 

SEE ALSO 

syslog(3), kill(2) 
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TALKD ( 8C ) 


MAINTENANCE COMMANDS 


TALKD (8C) 


NAME 

talkd - server for talk program 
SYNOPSIS 

/usr/etc/in.talkd 

DESCRIPTION 

Talkd is a server used by the talk(l) program. It listens at the udp port indicated in the “talk” service 
description; see services( 5). The actual conversation takes place on a tcp connection that is established by 
negotiation between the two machines involved. 

SEE ALSO 

services(5), talk(I), inetd(8) 

BUGS 

The protocol is architecture dependent, and can’t be relied upon to work between Suns and other machines. 
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MAINTENANCE COMMANDS 


TELNETD (8C) 


NAME 

telnetd — DARPA TELNET protocol server 
SYNOPSIS 

/usr/etc/in.telnetd hostport 
DESCRIPTION 

Telnetd is a server which supports the DARPA standard TELNET virtual terminal protocol. The TELNET 
server is invoked by inetd( 8C) each time there is a connection to the telnet service; see services (5). 

Telnetd operates by allocating a pseudo-terminal device (see pty(4)) for a client, then creating a login pro- 
cess which has the slave side of the pseudo-terminal as stdin, stdout, and stderr. Telnetd manipulates the 
master side of the pseudo terminal, implementing the TELNET protocol and passing characters between 
the client and login process. 

When a TELNET session is started up, telnetd sends a TELNET option to the client side indicating a wil- 
lingness to do “remote echo” of characters. The pseudo terminal allocated to the client is configured to 
operate in “cooked” mode, and with XTABS and CRMOD enabled (see tty (4)). Aside from this initial 
setup, the only mode changes telnetd will carry out are those required for echoing characters at the client 
side of the connection. 

Telnetd supports binary mode, and most of the common TELNET options, but does not, for instance, sup- 
port timing marks. 

SEE ALSO 

telnet(lC) 

BUGS 

A complete list of the options supported should be given here. 
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MAINTENANCE COMMANDS 


TFTPD ( 8C ) 


NAME 

tftpd - DARPA Trivial File Transfer Protocol server 
SYNOPSIS 

/usr/etc/in.tftpd [ -d ] [ port ] 

DESCRIPTION 

Tftpd is a server which supports the DARPA Trivial File Transfer Protocol. The TFTP server operates at 
the port indicated in the “tftp” service description; see services (5), and is invoked each time a datagram 
reaches this port by the internet server inetd( 8C). 

Due to the lack of authentication information, tftpd will allow only publicly readable files to be accessed. 
To do this, tftpd executes as uid —2 , gid -2 , assuming that no files exist with that owner or group. How- 
ever, nothing check this assumption or enforces this restriction. 

SEE ALSO 

tftp(lC) 

BUGS 

This server is known only to be self consistent (i.e. it operates with the user TFTP program, tftp{ 1C». 
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MAINTENANCE COMMANDS 


TIMED(8C) 


NAME 

timed - DARPA Time server 
SYNOPSIS 

/usr/etc/in.timed 

DESCRIPTION 

Timed is a server which supports the DARPA Time Server Protocol. The time server operates at the port 
indicated in the “time” service description; see services (5), and is invoked by inetd( 8C) each time there is 
a connection to the time server. 

SEE ALSO 

services(5), rdate(8), inetd(8) 

BUGS 

A more sophisticated facility that can accept broadcasts and synchronize clocks over an internet is needed. 
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TRPT ( 8C) 


NAME 

trpt - transliterate protocol trace 
SYNOPSIS 

/usr/etc/trpt [ -a ] [ -s ] [ — t ] [ — j ] [ -p hex-address ] [ system [ core ] ] 

DESCRIPTION 

Trpt interrogates the buffer of TCP trace records created when a socket is marked for ‘debugging’ (see set- 
sockopt( 2)), and prints a readable description of these records. When no options are supplied, trpt prints 
all the trace records found in the system grouped according to TCP connection protocol control block 
(PCB). 

OPTIONS 

-s Print a detailed description of the packet sequencing information, in addition to the normal output, 
-t Print the values for all timers at each point in the trace, in addition to the normal output 

-j Just give a list of the protocol control block addresses for which there are trace records. 

— p hex-address 

Show only trace records associated with the protocol control block who’s address follows. 

-a in addition to the normal output, print the values of the source and destination addresses for each 
packet recorded. 

The recommended use of trpt is as follows. Isolate the problem and enable debugging on the sockets) 
involved in the connection. Find the address of the protocol control blocks associated with the sockets 
using the -A option to netstat( 8). Then run trpt with the -p option, supplying the associated protocol con- 
trol block addresses. If there are many sockets using the debugging option, the -j option may be useful in 
checking to see if any trace records are present for the socket in question. 

If debugging is being performed on a system or core file other than the default, the last two arguments may 
be used to supplant the defaults. 

FILES 

/vmunix 

/dev/kmem 

SEE ALSO 

setsockopt(2), netstat(8) 

DIAGNOSTICS 

‘no namelist’ when the system image doesn’t contain the proper symbols to find the trace buffer; others 
which should be self explanatory. 

BUGS 

Should also print the data for each input or output, but this is not saved in the trace record. 

The output format is inscrutable, and should be described here. 
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MAINTENANCE COMMANDS 


TUNEFS (8) 


NAME 

tunefs - tune up an existing file system 
SYNOPSIS 

/usr/etc/tunefs [ -a maxcontig ] [ -d rotdelay ] [ -e maxbpg ] [ -m minfree ] special \ filesys 
DESCRIPTION 

Tunefs is designed to change the dynamic parameters of a file system which affect the layout policies. The 
parameters which are to be changed are indicated by the flags given below: 

-a maxcontig 

This specifies the maximum number of contiguous blocks that will be laid out before forcing a 
rotational delay (see -d below). The default value is one, since most device drivers require an 
interrupt per disk transfer. Device drivers that can chain several buffers together in a single 
transfer should set this to the maximum chain length. 

-d rotdelay 

This specifies the expected time (in milliseconds) to service a transfer completion interrupt and 
initiate a new transfer on the same disk. It is used to decide how much rotational spacing to place 
between successive blocks in a file. 

— e maxbpg 

This indicates the maximum number of blocks any single file can allocate out of a cylinder group 
before it is forced to begin allocating blocks from another cylinder group. Typically this value is 
set to about one quarter of the total blocks in a cylinder group. The intent is to prevent any single 
file from using up all the blocks in a single cylinder group, thus degrading access times for all files 
subsequently allocated in that cylinder group. The effect of this limit is to cause big files to do 
long seeks more frequently than if they were allowed to allocate all the blocks in a cylinder group 
before seeking elsewhere. For file systems with exclusively large files, this parameter should be 
set higher. 

— m minfree 

This value specifies the percentage of space held back from normal users; the minimum free space 
threshold. The default value used is 10%. This value can be set to zero, however up to a factor of 
three in throughput will be lost over the performance obtained at a 10% threshold. Note that if the 
value is raised above the current usage level, users will be unable to allocate files until enough 
files have been deleted to get under the higher threshold. 

SEE ALSO 

fs(5), newfs(8), mkfs(8), dumpfs(8) 

The Sun UNIX File System in the Sun System Internals Manual. 

BUGS 

This program should work on mounted and active file systems. Because the super-block is not kept in the 
buffer cache, the program will only take effect if it is run on dismounted file systems, (if run on the root 
file system, the system must be rebooted) 
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UPDATE (8) 


NAME 

update - periodically update the super block 

SYNOPSIS 

/etc/update 

DESCRIPTION 

Update is a program that executes the sync (2) primitive every 30 seconds. This insures that the file system 
is fairly up to date in case of a crash. This command should not be executed directly, but should be exe- 
cuted out of the initialization shell command file. 

SEE ALSO 

sync(2), sync(8), init(8) 
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MAINTENANCE COMMANDS 


UUCLEAN (8C) 


NAME 

uuclean - uucp spool directory clean-up 
SYNOPSIS 

/usr/lib/uucp/uuclean [ -p pre ] [ -n time ] [ -m ] 

DESCRIPTION 

Uuclean scans the spool directory for files with the specified prefix and deletes all those which are older 
than the specified number of hours. 

OPTIONS 

-ppre Scan for files with pre as the file prefix. Up to 10 -p arguments may be specified. A -p without 
any pre following deletes all files older than the specified time. 

-ntime Files whose age is more than time hours are deleted if the prefix test is satisfied (default time is 
72 hours). 

-m Send mail to the owner of the file when it is deleted. 

Uuclean will typically be started by cron(8). 

FILES 

/usr/lib/uucp directory with commands used by uuclean internally 

/usr/lib/uucp/spool spool directory 

SEE ALSO 

uucp(lC), uux(lC) 
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MAINTENANCE COMMANDS 


UUREC(8) 


NAME 

uurec - receive processed news articles via mail 

SYNOPSIS 

uurec 

DESCRIPTION 

uurec reads news articles on the standard input sent by sendnews($), decodes them, and gives them to 
inews(l) for insertion. 

SEE ALSO 

inews(l), readnews(l), recnews(8), sendnews(8), newscheck(l) 
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VIPW ( 8 ) 


MAINTENANCE COMMANDS 


VIPW ( 8 ) 


NAME 

vipw - edit the password file 

SYNOPSIS 

/etc/vipw 

DESCRIPTION 

Vipw edits the password file while setting the appropriate locks, and does any necessary processing after 
the password file is unlocked. If the password file is already being edited, then you will be told to try again 
later. The vi editor will be used unless the environment variable EDITOR indicates an alternate editor. 
Vipw performs a number of consistency checks on the password entry for root, and will not allow a pass- 
word file with a “mangled” root entry to be installed. 

SEE ALSO 

chsh(l), passwd(l), passwd(5), adduser(8) 

FILES 

/etc/ptmp 
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VMSTAT ( 8 ) 


NAME 

vmstat- report virtual memory statistics 
SYNOPSIS 

vmstat [ -fsS ] [ interval [ count ] ] 

DESCRIPTION 

Vmstat delves into the system and normally reports certain statistics kept about process, virtual memory, 
disk, trap and cpu activity. 

Without options, vmstat displays a one-line summary of the virtual memory activity since the system has 
been booted. If interval is specified, vmstat summarizes activity over the last interval seconds. If a count 
is given, the statistics are repeated count times. 

For example, the following command displays a summary of what the system is doing every five seconds. 
This is a good choice of printing interval since this is how often some of the statistics are sampled in the 
system. 

hal% vmstat 5 

procs memory page disk faults cpu 

r b w avm fre re at pi po fir de sr xO xl x2 x3 in sy cs us sy id 
2 0 0 918 286 0 0 0 0 0 0 0 1 0 0 0 4 12 5 3 5 91 

10 0 846 254 0 0 0 0 0 0 0 6 0 1 0 42 153 31 7 40 54 

10 0 840 268 0 0 0 0 0 0 0 5 0 0 0 27 103 25 8 26 66 

1 0 0 620 312 0 0 0 0 0 0 0 6 0 0 0 26 76 25 6 27 67 

“C 

hal% 

The fields of vmstat ’ s display are: 

procs Reports the number of processes in each of the three following states: 
r in run queue 

b blocked for resources (i/o, paging, etc.) 

w runnable or short sleeper (< 20 secs) but swapped 

memory Reports on usage of virtual and real memory. Virtual memory is considered active if it belongs 
to processes which are running or have run in the last 20 seconds, 
avm number of active virtual Kbytes 
fre size of the free list in Kbytes 

page Reports information about page faults and paging activity. The information on each of the fol- 
lowing activities is averaged each five seconds, and given in units per second, 
re page reclaims — but see the -S option for how this field is modified, 

at number of attaches — but see the -S option for how this field is modified, 

pi pages paged in 

po pages paged out 

ff pages freed per second 

de anticipated short term memory shortfall 
sr pages scanned by clock algorithm, per-second 

disk Reports number of disk operations per second (this field is system dependent). For Sun systems, 
four slots are available for up to four drives: “xO” (or “sO” for SCSI disks), “xl”, “x2”, and 
“x3”. 

faults Reports trap/interrupt rate averages per second over last 5 seconds, 
in (non clock) device interrupts per second 
sy system calls per second 

cs cpu context switch rate (switches/sec) 

cpu Gives a breakdown of percentage usage of CPU time. 
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MAINTENANCE COMMANDS 

VMSTAT ( 8 ) 

US 

user time for normal and low priority processes 


sy 

system time 


id 

cpu idle 



OPTIONS 

-f Report on the number of forks and vforks since system startup and the number of pages of virtual 
memory involved in each kind of fork. 


-s Display the contents of the sum structure, giving the total number of several kinds of paging- 
related events which have occurred since boot. 

-S Report on swapping rather than paging activity. This option will change two fields in vmstat’s 
“paging” display: rather than the “re” and “at” fields, vmstat will report “si” (swap-ins), and 
“so” (swap-outs). 

FILES 

/dev/kmem 

/vmunix 
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YPINIT ( 8 ) 


NAME 

ypinit - build and install yellow pages database 

SYNOPSIS 

ypinit -m 

ypinit -s master name 
DESCRIPTION 

ypinit sets up a yellow pages database on a YP server. It can be used to set up a master or a slave server. 
You must be the superuser to run it It asks a few, self-explanatory questions, and reports success or 
failure to the terminal. 

It sets up a master server using the simple model in which that server is master to all maps in the data base. 
This is the way to bootstrap the YP system; later if you want you can change the association of maps to 
masters. All databases are built from scratch, either from information available to the program at runtime, 
or from the ASCII data base files in /etc. These files are listed below under FILES . All such files should 
be in their "traditional" form, rather than the abbreviated form used on client machines. 

A YP database on a slave server is set up by copying an existing database from a running server. The 
master name argument should be the hostname of YP server (either the master server for all the maps, or a 
server on which the data base is up-to-date and stable). 

Refer to ypfiles(5) and ypserv(8) for an overview of the yellow pages. 

OPTIONS 

-m Indicates that the local host is to be the YP master. 

-s Set up a slave database. 

FILES 

/etc/passwd 

/etc/group 

/etc/hosts 

/etc/networks 

/etc/services 

/etc/protocols 

/etc/netgroup 

/etc/ethers 

SEE ALSO 

makedbm(8), ypfiles(5), yppush(8), ypxfr(8), ypmake(8), ypserv(8) 
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MAINTENANCE COMMANDS 


YPMAKE (8) 


NAME 

ypmake - rebuild yellow pages database 
SYNOPSIS 

cd /etc/yp ; make [ map ] 

DESCRIPTION 

The file called Makefile in letclyp is used by make to build the yellow pages database. With no arguments, 
make creates dbm databases for any YP maps that are out-of-date, and then executes yppush to notify slave 
databases that there has been a change. 

If you supply a map on the command line, make will update that map only. Typing make passwd will 
create and yppush the password database (assuming it is out of date). Likewise, make hosts and make net- 
works will create and yppush the host and network files, letclhosts and letc /networks. 

There are three special variables used by make : DIR, which gives the directory of the source files; 
NOPUSH, which when non-null inhibits doing a yppush of the new database files; and DOM, used to con- 
struct a domain other than the master’s default domain. The default for DIR is letc, and the default for 
NOPUSH is the null string. 

Refer to ypfiles(5) and ypserv(8) for an overview of the yellow pages. 

SEE ALSO 

make(l), makedbm(8), ypserv(8) 
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YPPASSWDD (8C) 


NAME 

yppasswdd - server for modifying yellow pages password file 
SYNOPSIS 

/usr/etc/rpc.yppasswdd file [ -m argl arg2 ... ] 

DESCRIPTION 

Yppasswdd is a server that handles password change requests from yppasswd(l). It changes a password 
entry in file, which is assumed to be in the format of passwd(5). An entry in file will only be changed if the 
password presented by yppasswdd 1) matches the encrypted password of that entry. 

If the -m option is given, then after file is modified, a make( 1) will be performed in /etc/yp. Any argu- 
ments following the flag will be passed to make. 

This server is not run by default, nor can it be started up from inetd( 8). If it is desired to enable remote 
password updating for the yellow pages, then an entry for yppasswdd should be put in the letclrc file of the 
host serving as the master for the yellow pages passwd file. 

EXAMPLE 

If the yellow pages password file is stored as letclyplsrclpasswd, then to have password changes pro- 
pagated immediately, the server should be invoked as 

/usr/etc/rpc.yppasswdd /etc/yp/src/passwd -m passwd DIR=/etc/yp/src 

FILES 

/etc/yp/Makefile 
SEE ALSO 

yppasswd(l), passwd(5), ypfiles(5), ypmake(8) 

CAVEAT 

This server will eventually be replaced with a more general service for modifying any map in the yellow 
pages 
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YPPOLL ( 8 ) 


NAME 

yppoll - what version of a YP map is at a YP server host 
SYNOPSIS 

yppoll [ -h host ] [ -d domain ] mapname 
DESCRIPTION 

yppoll asks a ypserv process what the order number is, and which host is the master YP server for the 
named map. If the server is a v.l YP protocol server, yppoll uses the older protocol to communciate with it. 
In this case, it also uses the older diagnostic messages in case of failure. 

OPTIONS 

-h host Ask the ypserv process at host about the map parameters. If host isn’t specified, the YP server for 
the local host is used. That is, the default host is the one returned by ypwhich( 8). 

— d domain 

Use domain instead of the default domain. 

SEE ALSO 

ypserv(8), ypfiles(5) 
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YPPUSH ( 8 ) 


NAME 

yppush - force propagation of a changed YP map 
SYNOPSIS 

yppush [ -d domain ] [ -v ] mapname 
DESCRIPTION 

yppush copies a new version of a Yellow Pages (YP) map from the master YP server to the slave YP 
servers. It is normally run only on the master YP server by the Makefile in lusr/etc/yp/ after the master 
databases are changed. It first constructs a list of YP server hosts by reading the YP map ypservers within 
the domain. Keys within the map ypservers are the ASCII names of the machines on which the YP servers 
run. 

A “transfer map” request is sent to the YP server at each host, along with the information needed by the 
transfer agent (the program which actually moves the map) to call back the yppush . When the attempt has 
completed (successfully or not), and the transfer agent has sent yppush a status message, the results may be 
printed to stdout. Messages are also printed when a transfer is not possible; for instance when the request 
message is undeliverable, or when the timeout period on responses has expired. 

Refer to ypfiles(5) and ypserv(8) for an overview of the yellow pages. 

OPTIONS 

-d Specify a domain . 

-v Verbose. This causes messages to be printed when each server is called, and for each response. If 
this flag is omitted, only error messages are printed. 

FILES 

/etc/yp/ domainname/ypserveis.{dir, pag } 

SEE ALSO 

ypserv(8), ypxfr(8), ypfiles(5), YP protocol specification 

BUGS 

In the current implementation (version 2 YP protocol), the transfer agent is ypxfr , which is started by the 
ypserv program. If yppush detects that it is speaking to a version 1 YP protocol server, it uses the older 
protocol, sending a version 1 YPPROC_GET request and issues a message to that effect Unfortunately, 
there is no way of knowing if or when the map transfer is performed for version 1 servers, yppush prints a 
message saying that an "old-style" message has been sent. The system administrator should later check to 
see that the transfer has actually taken place. 
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YPSERV ( 8 ) 


NAME 

ypserv - yellow pages server and binder processes 

SYNOPSIS 

/usr/etc/ypserv 

/etc/ypbind 

DESCRIPTION 

The yellow pages (YP) provides a simple network lookup service consisting of databases and processes. 
The databases are dbm( 3) files in a directory tree rooted at letclyp. These files are described in ypfiles(5). 
The processes are lusrletclypserv, the YP database lookup server, and letclypbind, the YP binder. The pro- 
grammatic interface to YP is described in ypclnt(3N). Administrative tools are described in yppush(8), 
ypxfr(8), yppoll(8), ypwhich(8), and ypset(8). Tools to see the contents of YP maps are described in 
ypcat(8), and ypmatch(l). Database generation and maintenance tools are described in ypinit(8), 
ypmake(8), and makedbm(8). 

Both ypserv and ypbind are daemon processes typically activated at system startup time from letc/rc. local, 
ypserv runs only on YP server machines with a complete YP database, ypbind runs on all machines using 
YP services, both YP servers and clients. 

The ypserv daemon’s primary function is to look up information in its local database of YP maps. The 
operations performed by ypserv are defined for the implementor by the YP protocol specification, and for 
the programmer by the header file <rpcsvc/yp_prot .h>. Communication to and from ypserv is by 
means of RPC calls. Lookup functions are described in ypclnt(3N), and are supplied as C-callable funtions 
in llibllibc. There are four lookup functions, all of which are performed on a specified map within some 
YP domain: Match, Get Jirst, Getjiext, and Get all. The Match operation takes a key, and returns the 
associated value. The Get Jirst operation returns the first key-value pair from the map, and Get next can 
be used to enumerate the remainder. Get_all ships the entire map to the requester as the response to a sin- 
gle RPC request. 

Two other functions supply information about the map, rather than map entries: Get_order_number, and 
Get master name . In fact, both order number and master name exist in the map as key- value pairs, but the 
server will not return either through the normal lookup functions. (If you examine the map with mak- 
edbm(S), however, they will be visible.) Other functions are used within the YP subsystem itself, and are 
not of general interest to YP clients. They include Do _you_serve_this domain? , Transfer map, and 
Reinitialize _internal_state. 

The function of ypbind is to remember information that lets client processes on a single node communicate 
with some ypserv process, ypbind must run on every machine which has YP client processes; ypserv may 
or may not be running on the same node, but must be running somewhere on the network. 

The information ypbind remembers is called a binding — the association of a domain name with the inter- 
net address of the YP server, and the port on that host at which the ypserv process is listening for service 
requests. The process of binding is driven by client requests. As a request for an unbound domain comes 
in, the ypbind process broadcasts on the net trying to find a ypserv process that serves maps within that 
domain. Since the binding is established by broadcasting, there must be at least one ypserv process on 
every net. Once a domain is bound by a particular ypbind, that same binding is given to every client pro- 
cess on the node. The ypbind process on the local node or a remote node may be queried for the binding of 
a particular domain by using the ypwhich( 1) command. 

Bindings are verified before they are given out to a client process. If ypbind is unable to speak to the 
ypserv process it’s bound to, it marks the domain as unbound, tells the client process that the domain is 
unbound, and tries to bind the domain once again. Requests received for an unbound domain will fail 
immediately. In general, a bound domain is marked as unbound when the node running ypserv crashes or 
gets overloaded. In such a case, ypbind will to bind any YP server (typically one that is less-heavily 
loaded) available on the net. 
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ypbind also accepts requests to set its binding for a particular domain. The request is usually generated by 
the YP subsystem itself. ypset{%) is a command to access the Set domain facility. It is for unsnarling 
messes, not for casual use. 

FILES 

If the file lusrletclyplypserv.log exists when ypserv starts up, log information will be written to this file 
when error conditions arise. 

SEE ALSO 

ypclnt(3N), ypfiles(5), ypcat(8), ypmatch(8), yppush(8), ypwhich(8), ypxff(8), ypset(8), YP protocol 
specification 
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NAME 

ypset - point ypbind at a particular server 
SYNOPSIS 

ypset [ —VI | — V2 ] [ -h host ] [ -d domain ] server 
DESCRIPTION 

ypset tells ypbind to get YP services for the specified domain from the ypserv process running on server. If 
server is down, or isn’t running ypserv, this is not discovered until a YP client process tries to get a binding 
for the domain. At this point, the binding set by ypset will be tested by ypbind. If the binding is invalid, 
ypbind will attempt to rebind for the same domain. 

ypset is useful for binding a client node which is not on a broadcast net, or is on a broadcast net which isn’t 
running a YP server host. It also is useful for debugging YP client applications, for instance where a YP 
map only exists at a single YP server host. 

In cases where several hosts on the local net are supplying YP services, it is possible for ypbind to rebind to 
another host even while you attempt to find out if the ypset operation succeeded. That is, you can type 
"ypset hostl”, and then "ypwhich”, which replies: ”host2", which can be confusing. This is a function of 
the YP subsystem’s attempt to load-balance among the available YP servers, and occurs when hostl does 
not respond to ypbind because it is not running ypserv (or is overloaded), and hostl, running ypserv, gets 
the binding. 

server indicates the YP server to bind to, and can be specified as a name or an IP address. If specified as a 
name, ypset will attempt to use YP services to resolve the name to an IP address. This will work only if the 
node has a current valid binding for the domain in question. In most cases, server should be specified as an 
IP address. 

Refer to ypfiles(5) and ypserv(8) for an overview of the yellow pages. 

OPTIONS 

-VI 

-V2 


-h host 

-d domain 

SEE ALSO 

ypwhich(l), ypserv(8), ypfiles(5) 


Bind server for the (old) v.l YP protocol. 

Bind server for the (current) v.2 YP protocol. 

If no version is supplied, ypset, first attempts to set the domain for the (current) v.2 protocol. 
If this attempt fails, ypset, then attempts to set the domain for the (old) v.l protocol. 

Set ypbind’s binding on host, instead of locally, host can be specified as a name or as an IP 
address. 

Use domain , instead of the default domain. 
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NAME 

ypwhich - what machine is the YP server? 

SYNOPSIS 

ypwhich [ -d domainname ] [ hostname ] 
ypwhich [ -d domainname ] [ -t ] m [ mname ] 

DESCRIPTION 

Ypwhich tells which YP server supplies yellow pages to a YP client, and which YP server is the master for 
a map. If invoked without arguments, it gives the YP server for the local machine. If hostname is 
specified, that machine is queried to find out which YP master it is using. 

If the -m switch is used without mname, a list of every map in the domain and the master of each will be 
printed. If mname is specified, only the master YP server for that map is printed. Mname may be a map- 
name, or a nickname for a mapname. Mapnames and nicknames are described in ypcat( 1). 

OPTIONS 

-d 

-m 

-t 

SEE ALSO 

ypfiles(5), rpcinfo(8), yppush(8), ypserv(8) 


Domainname specifies the name of a YP domain. The default is the default domain for the local 
machine. 

Find the master YP server for a map, or for all maps in a domain. No hostname may be specified 
with -m. 

Inhibit nickname translation; useful if there is a mapname identical to a nickname. This is not true 
of any Sun-supplied map. 
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NAME 

ypxfr - transfer a YP map from some YP server to here 
SYNOPSIS 

ypxfr [ -f ] [ -h host ] [ -d domain ] [ -c ] [ -C t id prog ipadd port ] mapname 
DESCRIPTION 

ypxfr moves a YP map to the local host by making use of normal YP services. It creates a temporary map 
in the directory letc/ypl domain (which must already exist), fills it by enumerating the map’s entries, fetches 
the map parameters (master and order number) and loads them. It then deletes any old versions of the map 
and moves the temporary map to the real mapname. 

If ypxfr is run interactively, it writes its output to the terminal. However, if it’s invoked without a control- 
ling terminal, and if the log file letclyplypxfr.log exists, it will append all its output to that file. Since ypxfr 
is most often run from /usr/lib/crontab , or by ypserv , you can use the log file to retain a record of what 
was attempted, and what the results were. 

For consistency between servers, ypxfr should be run periodically for every map in the YP data base. Dif- 
ferent maps change at different rates: the services. byname map may not change for months at a time, for 
instance, and may therefore be checked only once a day in the wee hours. You may know that mail.aliases 
or hosts. byname changes several times per day. In such a case, you may want to check hourly for updates. 
A crontab( 5) entry can be used to perform periodic updates automatically. Rather than having a separate 
crontab entry for each map, you can group comands to update several maps in a shell script. Examples 
(mnemonically named) are in letc/yp: ypxfr lperday.sh, ypxfr _2per day., sh, and ypxfr _lperhour.sh . They 
can serve as reasonable first cuts. 


Refer to ypfiles(5) and ypserv(8) for an overview of the yellow pages. 

OPTIONS 

-f Force the transfer to occur even if the version at the master is not more recent than the 

local version. 


-c Don’t send a "Clear current map" request to the local ypserv process. Use this flag if 

ypserv is not running locally at the time you are running ypxfr. Otherwise, ypxfr will 
complain that it can’t talk to the local ypserv, and the transfer will fail. 

-h host Get the map from host , regardless of what the map says the master is. If host is not 

specified, ypxfr will ask the YP service for the name of the master, and try to get the map 
from there, host may be a name or an internet address in the form a.b.c.d . 

-d domain Specify a domain other than the default domain. 

— C tid prog ipadd port 

This option is only for use by ypserv. When ypserv invokes ypxfr, it specifies that ypxfr 
should call back a yppush process at the host with IP address ipaddr , registered as pro- 
gram number prog , listening on port port , and waiting for a response to transaction tid . 

FILES 

/etc/yp/ypxfr.log, /etc/yp/ypxfr_lperday.sh, /etc/yp/ypxff_2perday.sh, /etc/yp/ypxfr_lperhour.sh, 

/usr/lib/crontab 


SEE ALSO 

ypfiles(5), ypserv(8), yppush(8), YP protocol spec 
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Special Characters 
! mail command, 195 
# mail command, 195 
%job & — job to background — csh, 70 
% j ob — job to foreground — csh, 70 
. shell command — sh, 298 
: shell command — sh, 298 
= mail command, 195 
? mail command, 195 

@ — arithmetic on shell variables — csh, 70 
I mail command, 197 
' ! mail tilde escape, 198 
~ . mail tilde escape, 198 
~ : mail tilde escape, 198 
'< mail tilde escape, 199 
~ ? mail tilde escape, 199 
mail tilde escape, 198 
' | mail tilde escape, 199 

A 

~A mail tilde escape, 199 

~a mail tilde escape, 199 

abort printer — lpc, 543 

ac — login accounting, 490 

login accounting — ac, 490 

accounting on or off, 603 

accton — accounting on or off, 603 

adb — debugger, 2 

adb scripts — adbgen, 491 

adbgen — generate adb script, 491 

addbib — create bibliography, 3 

additional paging/swapping devices, specify — swapon, 616 

address resolution display and control — arp, 496 

adduser — add new user account, 493 

ad jacentscreens, 5 

admin — adminster SCCS, 6 

administration 

install — install files, 165 
adventure — exploration game, 416 
alias mail command, 195, 196 
alias — shell macros — csh, 64 
alias substitution 

in C-Shell, 60 

allnet mail environment variable, 200 
alloc — show memory use — csh, 64 


allow messages — mesg, 212 
alterprocess priority — renice, 582 
alternates mail command, 195 
alwaysignore mail environment variable, 200 
analyze — crash analyzer, 495 
append mail environment variable, 200 
ar — library maintenance, 9 
archive 

ar — library maintenance, 9 
archive tapes — tar, 338 
archives 

copy, 51 

cpio — copy archives, 51 
argument list processing 

in C-Shell, 73 thru 74 

arithmetic — drill in number facts, 417 

arp — address resolution display and control, 496 

as — assembler, 11 

ASCII dump file — od, 224 

ascii — ASCII character set, 470 

askcc mail environment variable, 200 

ask sub mail environment variable, 200 

at — do job at specified time, 13 

autoboot procedures — reboot, 580 

autoprint mail environment variable, 200 

awk — scan and process patterns, 14 

B 

~b mail tilde escape, 199 
backgammon — backgammon game, 418 
backspace magnetic tape files — mt, 218 
backspace magnetic tape records — mt, 218 
backup dumps — dump, 515 
bang mail environment variable, 200 
banner — large banner, 420 
basename — strip filename affixes, 17 
bballs — black and white demo, 422 
bbounce — black and white demo, 422 
be — calculator language, 18 
bed — convert to antique media, 421 
bdemos — black and white demo, 422 
bdraw — interactive graphics drawing, 434 
bg — job to background — csh, 65 
bibliographic database 

rof f bib — insert literature references, 270 


- 643 - 


Index Continued 


bibliographic references 

refer — insert literature references, 263 
bibliography management 
create or extend, 3 

indxbib — make inverted index, 164 
lookbib — find bibliographic references, 180 
sortbib — sort bibliographic database, 311 
biff — mail notifier, 20 
binary file transmission 

uudecode — decode binary file, 377 
uuencode — encode binary file, 377 
binmail — version 7 mail, 21 
biod daemon, 566 
b jump — black and white demo, 422 
black and white demos 
bbounce, 422 
bdemos, 422 
b jump, 422 
bphoto, 422 
brotcube, 422 
blocks 

count, in file — sum, 322 
boggle — boggle game, 423 
bootstrap procedures — reboot, 580 
bootstrap PROM monitor program, 553 
Bourne Shell — sh, 294 thru 301 
false command, 120 

Bourne Shell commands, 294 thru 295, 298 thru 300 
.,298 
:, 298 

break, 298 
case, 294 
cd, 298 

continue, 298 
do, 294 
done, 294 
echo, 299 
elif, 294 
else, 294 
esac, 294 
eval, 299 
exec, 299 
exit, 299 
export, 299 
f i, 294 
for, 294 
hash, 299 
if, 294 
in, 294 
login, 299 
pwd, 299 
read, 299 
readonly, 299 
return, 299 
set, 299 thru 300 
shift, 300 
test, 300 
then, 294 
times, 300 
trap, 300 
type, 300 
umask, 300 


Boume Shell commands, continued 
unset, 300 
until, 294 
wait, 300 
while, 294 

Boume Shell functions, 295 
Boume Shell parameters, 295 thru 296 
CDPATH, 296 
HOME, 296 
IFS, 296 
MAIL, 296 
MAILCHECK, 296 
MAILPATH, 296 
PATH, 296 
PS1, 296 
PS2, 296 
SHELL, 296 

bphoto — black and white demo, 422 
break shell command — sh, 298 
break — exit loop — csh, 65 
breaksw — exit switch — csh, 65 
broadcast messages 

rwall — to all users on network, 276, 396 
brotcube — black and white demo, 422 
bsuncube — display 3-D Sun logo, 426 
build programs — make, 206 thru 210 
make random library — ranlib, 258 
build system configuration files — conf ig, 501 
build yellow pages database — ypinit, 633 

c 

C compiler, 27 
' c mail tilde escape, 199 
C programming language 

cpp — C preprocessor, 53 
ctags — create tags file, 76 
indent — format C source, 161 
mkstr — create C error messages, 214 
tcov — code coverage tool, 343 
vgrind — make formatted C listings, 384 
xstr — extract strings from C code, 407 
C programming languages 

lint — C program verifier, 174 
C Shell variables, 70 thru 73 
argv, 71 
cdpath, 71 
cwd, 71 
echo, 71 
hardpaths, 71 
histchars, 71 
history, 71 
home, 71 
ignoreeof, 71 
mail, 71 
noclobber, 71 
noglob, 71 
nonomatch, 71 
notify, 71 
path, 71 
prompt, 72 
savehist, 72 
shell, 72 
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C Shell variables, continued 
status, 72 
time, 72 
verbose, 73 
C-Shell co mm ands 

% job — job to foreground, 70 
% job & — job to background, 70 
@ — arithmetic on shell variables, 70 
alias — shell macros, 64 
alloc — show memory use, 64 
bg — job to background, 65 
break — exit loop, 65 
break sw — exit switch, 65 
case — selector in switch, 65 
cd — change directory, 65 
chdir — change directory, 65 
continue — cycle loop, 65 
default — catchall in switch, 65 
dir s — print directory stack, 65 
echo — echo arguments, 65 
else — alternative commands, 65 
end — end loop, 65 
endif — end conditional, 65 
endsw — end switch, 65 
eval — re-evaluate shell data, 65 
exec — execute command, 65 
exit — exit shell, 66 
f g — job to foreground, 66 
f oreach — loop on list of names, 66 
glob — filename expand argument list, 66 
goto — command transfer, 66 
hashstat — display hashing statistics, 66 
history — display history list, 66 
if — conditional statement, 66 
jobs — display job list, 67 
kill — kill jobs and processes, 67 
limit — alter resource limitations, 67 
login — login new user, 67 
logout — end session, 67 
nice — run low priority process, 67 
nohup — run command immune to hangups, 68 
notify — request immediate notification, 68 
onintr — handle interrupts in scripts, 68 
popd — pop shell directory stack, 68 
pushd — push shell directory stack, 68 
rehash — recompute command hash table, 68 
repeat — execute command repeatedly, 68 
set — change value of shell variable, 68 
setenv — set variable in environment, 69 
shift — shift argument list, 69 
source — read commands from file, 69 
stop — halt job or process, 69 
suspend — suspend shell, 69 
switch — multi-way branch, 69 
time — time command, 69 
umask — change/display file creation mask, 69 
unalias — remove aliases, 70 
unhash — discard hash table, 70 
unlimit — remove resource limitations, 70 
unset — discard shell variables, 70 
un setenv — remove environment variables, 70 
wait — wait for background process, 70 
while — repeat commands, 70 
cal — display calendar, 23 


calculator, 82 

calendar — reminder service, 24 
call-graph 

display profile data, 146 
canfield — canfield solitaire card game, 427 
case shell command — sh, 294 
case — selector in switch — csh, 65 
cat — concatenate files, 25 
C/A/T interpreter — pti, 250 
catman — create cat files for manual, 497 
cb — C beautifier, 26 

try indent — format C source, 161 
cballs — color demo, 432 
cc — C compiler, 27 
ccat — compress files, 49 
cd — change directory, 30 
cd shell command — sh, 298 
cd mail command, 195 
cd — change directory — csh, 65 
cdc — change delta commentary, 31 
CDPATH shell parameter — sh, 296 
cdraw — color demo, 432, 434 
change 

default shell, 36 
delta commentary, 31 
directory, 30 
group, 34 
login shell, 36 
mode of file, 35 
permissions of file, 35 
working directory, 30 
change login password — passwd, 227 
change login password in yellow pages — yppasswd, 413 
change name of directory — mv, 219 
change name of file — mv, 219 
change priority of command — nice, 220 
change process priority — reni ce, 582 
character translation — tr, 357 
characters for equations — eqnchar, 471 
characters in file 

count — wc, 397 
chase — escape killer robots, 428 
chdir mail command, 195 
chdir — change directory — csh, 65 
check directory — dcheck, 509 
check file system — fsck, 524 
check spelling — spell, 312 
checkeq — check eqn constructs, 107 
checknr — check nroff/troff files, 33 
chess — chess game, 429 
ches stool — chess game, 430 
chgrp — change group, 34 
ching — book of changes, 431 
chmod — change mode, 35 
chown — change owner of file, 498 
chsh — change shell, 36 
clean print queue — lpc, 543 
clean UUCP spool area — uuclean, 628 
clear — clear screen, 37 
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clear i-node — clri, 499 

clear_colormap — clear hardware color map, 38 

clock — display time in window, 40 

clri — clear i-node, 499 

cmd mail environment variable, 200 

cmp — compare files, 43 

code coverage tool — tcov, 343 

code formatter 

indent — formatC source, 161 
col — filter reverse paper motions, 44 
colcrt — document previwer, 45 
color demo 

cballs, 432 
cdraw, 432 
cphoto, 432 
cpipes, 432 
cshowmap, 432 
csnow, 432 
csuncube, 432 
csunlogo, 432 
cvlsi, 432 

colrra — remove columns from file, 46 
columns 

print in multiple — pr, 239 
remove from file, 46 
comb — combine deltas, 47 
combine SCCS deltas, 47 
comm — find commonality, 48 
command 

change priority of — nice, 220 
describe — whati s, 399 
locate — whereis,400 
run immune to hangup — nohup, 220 
co mm and execution 
in C-Shell, 73 
command interpreter 

csh — C Shell, 57 thru 75 
sh — Bourne Shell, 294 thru 301 
command substitution 
in C-Shell, 62 
commands 

introduction, 1 

commands to Bourne Shell, 294 thru 295, 298 thru 300, see also 
Bourne Shell commands 
communications 

cu — connect to remote system, 351 
enroll — enroll for secret mail, 406 
mail — send and receive mail, 193 thru 202 
permit or deny messages — mesg, 212 
talk — talk to another user, 337 
telnet — TELNET interface, 347 
tftp — trivial file transfer program, 349 
tip — connect to remote system, 351 
uuclean — clean UUCP spool area, 628 
uucp — UNIX to UNIX copy, 375 
uudecode — decode binary file, 377 
uuencode — encode binary file, 377 
uulog — UUCP log, 375 
uusend — send file to remote host, 378 
uux — UNIX to UNIX command execution, 379 
write — write to another user, 404 


communications, continued 

xget — receive secret mail, 406 
xsend — send secret mail, 406 
compare 
files, 43 

files differentially, 94 
three-way differential, 96 

compare versions of SCCS file — sccsdif f, 283 
compile Pascal programs — pc, 228 
compiler generator, 116,408 
compiler generators 

lex — generate lexical analyzer, 173 
compilers 

cc — C compiler, 27 
compress — compress files, 49 
compress files, 49 
comsat — biff server, 500 
concatenate files 

cat — concatenate files, 25 
conf ig — build system configuration files, 501 
configuration files 

build — conf ig, 501 

configure network interface parameters — ifconfig, 536 

connect to remote system — cu, 351 

connect to remote system — tip, 351 

continue shell command — sh, 298 

continue — cycle loop — csh, 65 

control line printer — lpc, 543 thru 544 

control magnetic tape — mt, 218 

conv mail environment variable, 200 

convert 

spaces to tabs, 113 
tabs to spaces, 113 
convert and copy files, 84 
convert foreign font files — vswap, 391 
convert units — units, 372 
copy 

archives, 51 
files, 50 

copy files from remote machine — rep, 262 

copy mail command, 195 

copy standard output to many files — tee, 344 

Copy mail command, 195 

core images 

get of process, 137 
count blocks in file — sum, 322 
count lines, words, characters in file — wc, 397 
cp — copy files, 50 
cphoto — color demo, 432 
cpio — copy archives, 51 
cpipes — color demo, 432 
epp — C preprocessor, 53 
CPU PROM monitor program, 553 
crash analyzer — analyze, 495 
crash — crash procedure, 506 
create 

bibliography — addbib, 3 
delta, 88 

SCCS data bases, 6 
SCCS delta, 88 
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create, continued 

tags file, 76 

create cat files for manual — catman, 497 

create directory — ink dir, 213 

create error log — dmesg, 514 

create file system — mkf s, 550 

create font width table — vwidth, 393 

create mail aliases database — newaliases, 564 

create new file system — newf s, 565 

create permuted index — ptx, 251 

create prototype file system — mkproto, 552 

make random library — rani ib, 258 

create script of terminal session — script, 287 

create special file — mknod, 551 

create system configuration files — conf ig, 501 

create system log entry — syslog, 335 

create yellow pages database — ypinit, 633 

create yellow pages dbm file — makedbm, 547 

cribbage — cribbage card game, 433 

cron — clock daemon, 508 

cross reference Pascal program — pxref , 256 

crt mail environment variable, 200 

crypt — encrypt, 56 

csh — C shell, 57 thru 75 

cshowmap — color demo, 432 

csnow — color demo, 432 

csuncube — color demo, 432 

c sun logo — color demo, 432 

ctags — create tags file, 76 

cu — connect to remote system, 351 

current domain 

set or display, 97 
curve fitting 

spline — interpolate smooth curve, 313 
cvlsi — color demo, 432 

D 

~d mail tilde escape, 199 
daemons 

biod daemon, 566 
nfsd daemon, 566 
sprayd — spray server, 614 
DARPA TELNET protocol server — telnetd, 622 
DARPA Time server — timed, 624 
DARPA to RPC mapper — portmap, 570 
Data Encryption Standard, 91 
database operator — join, 166 
date — date and time, 77 
dbx — debugger, 78 
dbxtool — debugger, 80 
dc — desk calculator, 82 
dcheck — directory consistency check, 509 
dd — convert and copy, 84 
DEAD mail environment variable, 200 
debug mail environment variable, 200 
debug network — ping, 569 
debug tools 

adb — debugger, 2 

adbgen — generate adb script, 491 


debug tools, continued 

d, 78 

dbxtool — debugger, 80 
decimal dump file — od, 224 
decode binary file — uudecode, 377 
decode files, 56 
crypt — decrypt, 56, 91 
decrypt files, 56 

default — catchall in switch — c sh, 65 
defining Bourne Shell functions, 295 
delete 

columns from file, 46 
filename affixes, 17 
nroff, troff, tbl and eqn constructs, 90 
delete directory — rmdir, 269 
delete file or directory — rm, 267 
delete mail command, 195 
delete outdated news articles — expire, 522 
delete print jobs — Iprm, 187 
delete repeated lines — uniq, 371 
delta 

change commentary, 31 
combine, 47 
remove — rmdel, 268 
delta — make delta, 88 
demos and games 
introduction, 415 

demount file system — uraount, 557 
deny messages — mesg, 212 
derof f — remove troff constructs, 90 
des — data encryption, 91 
describe command — what is, 399 
desk calculator, 82 
devices 

paging, specify — swapon, 616 
swapping, specify — swapon, 616 
df — display free space, 93 
diag — initialize/diagnose disk, 510 
diagnose/initialize disk — diag, 510 
diagnostics 

gxtest — graphics board diagnostics, 532 
imemtest — memory diagnostic, 537 
diagnostics — sysdiag, 618 
dif f — differential compare, 94 
dif f 3 — three-way differential compare, 96 
directory 

change name of — mv, 219 

change working, 30 

check consistency — dcheck, 509 

delete — rm, 267 

delete — rmdir, 269 

differential compare, 94 

display name of working — pwd, 252 

erase — rm, 267 

erase — rmdir, 269 

list contents of — Is, 189 

make — mkdir, 213, 214 

make link to — In, 176 

move — mv, 219 

purge — rm, 267 

purge — rmdir, 269 
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directory, continued 
remove — rm, 267 
remove — rmdir, 269 
rename — mv, 219 

di r s — print directory stack — c sh, 65 
disable print queue — lpc, 543 
discard mail command, 195, 196 
disk 

dkinf o — geometry information, 513 
disk diagnose/initialize — diag, 510 
disk diagnostics — sysdiag, 618 
display 

call-graph profile data, 146 
current domain, 97 
current host identifier, 156 
current host name, 157 
date, 77 

date and time, 77 
disk usage, 98 
first lines of file, 154 
free space in file system, 93 
group membership, 153 
identifier of current host, 156 
name of current host, 157 
time and date, 77 
time in window, 40 
display editor — vi, 386 
display effective user name — whoami, 403 
display file names — 1 s, 189 
display last commands — lastcomm, 169 
display last part of file — tail, 336 
display name list — nm, 221 
display online manuals — man, 211 
display printer queue — lpq, 182 
display process status — ps, 247 
display program profile — prof, 243 
display SCCS file editing status — sact, 278 
display status of local hosts — rup, 273, 274 
display system up time — uptime, 373 
display users on system — users, 374 
display waiting mail — prmail, 242 
display working directory name — pwd, 252 
dkinf o — disk geometry information, 513 
dmesg — create error log, 514 
do shell command — sh, 294 
document preparation 

bibliography management, 3 
document production 

checknr — check nroff/troff files, 33 

col — filter reverse paper motions, 44 

colcrt command, 45 

delete nroff, troff, tbl and eqn constructs, 90 

eqnchar — special characters for equations, 471 

equation processor, 107 

indxbib — make inverted index, 164 

lookbib — find bibliographic references, 180 

man — macros to format manual pages, 479 

mathematical formatting, 107 

me — macro package, 481 

ms — macro package, 483 

nroff — document formatter, 222 


document production, continued 

pti — (old) troff interpreter, 250 
ptx — generate permuted index, 251 
refer — insert literature references, 263 
remove nroff, troff, tbl and eqn constructs, 90 
rof fbib — print bibliographic database, 270 
set equations, 107 
simple formatter, 124 

soelim — eliminate .so’s from nroff input, 308 
sortbib — sort bibliographic database, 311 
spell — check spelling, 312 
tbl — table formatter, 342 
troff — typeset documents, 359 
vf ontinf o — examine font files, 383 
vtrof f — format document for raster printer, 392 
vwidth — make font width table, 393 
domain 

set or display current, 97 
domainname — set/display domain name, 97 
done shell command — sh, 294 
dot mail environment variable, 200 
dp mail command, 195 
draw graph, 148 
dt mail command, 195 
du — display disk usage, 98 
dump — dump file system, 515 
dump frame buffer image — screendump, 284 
dumpf s — dump file system information, 517 

E 

~e mail tilde escape, 199 

echo — echo arguments, 99, 299 

echo mail command, 195 

echo — echo arguments — csh, 65 

ed — line editor, 100 

edit 

fonts, 126 

edit — line editor, 111 
edit mail command, 195 
edit password file — vipw, 630 
editing text 

edit — line editor, 111 
ex — line editor, 111 
sed — stream editor, 288 
editing text files 

ed — line editor, 100 
editor 

icon, 158 

EDITOR mail environment variable, 200 

egrep — pattern scanner, 150 

elif shell command — sh, 294 

eliminate .so’s from nroff input — soelim, 308 

else shell command — sh, 294 

else mail command, 196 

else — alternative commands — csh, 65 

emulate Tektronix 4014 — tektool, 345 

enable print queue — lpc, 543 

encode binary file — uuencode, 377 

encode files, 56 

encrypt, 91 
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encrypt files, 56 
encrypted mail 

enroll for — enroll, 406 
receive — enroll, 406 
send — xsend, 406 
encryption key 

generate — makekey, 549 
end — end loop — csh, 65 
endif mail command, 196 
endif — end conditional — csh, 65 
endsw — end switch — csh, 65 
enroll — enroll for secret mail, 406 
environment 

display variables — printenv, 241 
tset — set terminal characteristics for, 362 
environment variables 
in C-Shell, 70 thru 73 

environment variables in mail, 199 thru 202, see also mail 
environment variables 

eqn 

remove constructs, 90 
eqn — mathematical typesetting, 107 
eqnchar — special characters for equations, 471 
erase directory — rmdir, 269 
erase file or directory — rm, 267 
erase magnetic tape — mt, 218 
error — analyze error messages, 109 
esac shell command — sh, 294 
escape mail environment variable, 200 
eval shell command — sh, 299 
eval — re-evaluate shell data — csh, 65 
evaluate expressions, 1 14 
ex — line editor, 111 
exec shell command — sh, 299 
exec — execute command — csh, 65 
execute co mm ands at specified times — cron, 508 
executing non-builtin commands 
in C-Shell, 73 

exit shell command — sh, 299 

exit mail command, 195, 198 

exit — exit shell — csh, 66 

expand — expand tabs, 113 

expi re — remove outdated news articles, 522 

export shell command — sh, 299 

expr — evaluate expressions, 1 14 

expression evaluation, 114 

extend 

bibliography — addbib, 3 
extract strings from C code — xstr, 407 
eyacc — compiler generator, 1 16 

F 

~f mail tilde escape, 199 
f 7 7 — FORTRAN compiler, 1 17 
fastboot — reboot system, 523 
fasthalt — halt system, 523 
fg — job to foreground — csh, 66 
fgrep — pattern scanner, 150 
f i shell command — sh, 294 


file 

browse through text — more, 215 
browse through text — page, 215 
change name of — mv, 219 
change ownership — chown, 498 
copy from remote machine — rep, 262 
count lines, words, characters in — wc, 397 
delete — rm, 267 
display last part of — tail, 336 
dump — od, 224 
erase — rm, 267 
find lines in sorted — look, 179 
identify version — what, 398 
make link to — In, 176 
move — mv, 219 
print — lpr, 184 
purge — rm, 267 
remove — rm, 267 
rename — mv, 219 
reverse lines in — rev, 264 
send to remote host — uusend,378 
split into pieces — split, 314 
sum — sum and count blocks in file, 322 
update last modified date of — touch, 356 
file — get file type, 121 
file mail command, 195 
file system 

cd — change directory, 30 
check and repair — f s ck, 524 
check consistency — icheck, 535 
check directory — dcheck, 509 
create new — newfs, 565 
demount — umount, 557 
display free space, 93 
dump information — dumpf s, 517 
free space display, 93 
make — mkfs, 550 
make prototype — mkproto, 552 
mount — mount, 557 
summarize ownership — quot, 575 
tune — tunef s, 626 
unmount — umount, 557 
where am I — pwd, 252 
file system dump — dump, 515 
file system hierarchy — hier, 472 
file system restore — restore, 584 
file transfer protocol 
ftp command, 132 

file transfer protocol server — f tpd, 527 
filename substitution 

in C-Shell, 62 thru 63 

files 

basename — strip affixes, 17 
cat — concatenate, 25 
ccat — compress files, 49 
chmod — change mode, 35 
emp — compare files, 43 
colrm — remove columns from, 46 
comm — find commonality, 48 
compare, 43 

compare three-way differential, 96 
compress — compress files, 49 
convert and copy, 84 
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files, continued 
copy, 50 

copy standard output to many — tee, 344 

cp — copy files, 50 

cpio — copy archives, 5 1 

crypt — encrypt/decrypt, 56 

decode, 56 

decrypt, 56 

determine type of, 121 

differential compare, 94 

display first lines of, 154 

display names — Is, 189 

encode, 56 

encrypt, 56 

find, 122 

find differences, 94 

prepare files for printing — pr, 239 

search for patterns in, 150 

sort — sort or merge files, 309 

split FORTRAN file, 131 

three-way differential compare, 96 

transfer, 132 

uncompress — uncompress files, 49 

filter 

reverse paper motions, 44 
find — find files, 122 
find lines in sorted file — look, 179 
find literature references — refer, 263 
find object file size — si ze, 306 
find ordering for object library — lorder, 181 
find patterns in file, 150 

find printable strings in binary file — strings, 315 

find program — where is, 400 

fish — Go Fish game, 436 

flush disk activity — sync, 334 

fmt — simple formatter, 124 

fold — fold long lines, 125 

folder mail command, 195 

folder mail environment variable, 200 

folders mail command, 196 

followup mail command, 196 

Followup mail command, 196 

font 

vwidth — make font width table, 393 
font files 

convert foreign — vswap, 391 
fontedit — font editor, 126 
for shell co mm and — sh, 294 
foreach — loop on list of names — csh, 66 
format C programs — indent, 161 
format document for raster printer — vt ro f f , 392 
format tables — tbl, 342 
FORTRAN 

f 77 — FORTRAN compiler, 117 
print file, 129 
split file, 131 
FORTRAN language 

ratf or — rational FORTRAN, 261 
FORTRAN programming language 
ctags — create tags file, 76 
fortune — get fortune, 437 


f pr — print FORTRAN file, 129 

from — who is mail from, 130 

from mail command, 196 

f sck — check and repair file system, 524 

f s i rand — install random inode generation numbers, 526 

f split — split FORTRAN file, 131 

ftp — file transfer, 132 

f tpd — file transfer protocol server, 527 

functions in Bourne Shell, 295 

G 

games and demos 
introduction, 415 

gcore — core image of process, 137 
generate adb script — adbgen, 491 
generate encryption key — makekey, 549 
generate lexical analyzer — lex, 173 
generate Pascal execution profile — pxp, 254 
generate permuted index — ptx, 251 
get — get SCCS file, 138 
get magnetic tape unit status — mt, 218 
get terminal name — tty, 368 
get terminal options — stty, 317 
gettable — get NIC host tables, 529 
getty — set terminal mode, 530 
gfxtool, 144 

glob — filename expand argument list — csh, 66 
goto — command transfer — c sh, 66 
gprof — call-graph profile, 146 
graph — draw graph, 148 
graphics 

spline — interpolate smooth curve, 313 
vplot — plot on Versatec, 388 
graphics board diagnostics — gxtest, 532 
graphics filters — plot, 237 
graphics tool, 144 
grep — pattern scanner, 150 
group 

change, 34 

group mail command, 195, 196 
groups — display group membership, 153 
gxtest — graphics board diagnostics, 532 

H 

'h mail tilde escape, 199 
halt — stop processor, 533 
halt system — f asthalt, 523 
hangman — hangman game, 441 
hard link 

make — In, 176 
hash shell command — sh, 299 
hashstat — display hashing statistics — csh, 66 
head — display head of file, 154 
header mail environment variable, 200 
headers mail command, 196 
help — get SCCS help, 155 
help mail command, 196 
hexadecimal dump file — od, 224 
hier — file system hierarchy, 472 
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history — display history list — csh, 66 

hold mail command, 196, 197 

hold mail environment variable, 200 

HOME mail environment variable, 199 

HOME shell parameter — sh, 296 

ho st id — display host ID, 156 

hostname — display host name, 157 

htable — convert NIC standard format host tables, 534 

I 

~i mail tilde escape, 199 
i-node 

clear — clri, 499 
I/O statistics report — iostat, 541 
icheck — file system consistency check, 535 
iconedit, 158 

identify file version — what, 398 

if shell co mma nd — sh, 294 

if mail command, 196 

if — conditional statement — csh, 66 

if conf ig — configure network interface parameters, 536 

IFS shell parameter — sh, 296 

ignore mail command, 195, 196 

ignore mail environment variable, 200 

ignoreeof mail environment variable, 200 

imemtest — memory diagnostic, 537 

in shell command — sh, 294 

incremental file system dump — dump, 515 

incremental file system restore — restore, 584 

indent — format C source, 161 

indexing 

ptx — generate permuted index, 251 
indxbib — make inverted index, 164 
inetd — internet services daemon, 538 
information handling 

awk — scan and process patterns, 14 

be — calculator language, 18 
inhibit messages — mesg, 212 
in it — process control initialization, 539 
initialize/diagnose disk — diag, 510 
insert literature references — refer, 263 
install — install files, 165 
install yellow pages database — ypinit, 633 
interactive graphics drawing — bdraw, 434 
Internet file transfer protocol server — f tpd, 527 
interpolate smooth curve — spline, 313 
interpret (old) troff output — pti, 250 
interpret Pascal — px, 253 
introduction to commands, 1 
introduction to games and demos, 415 
introduction to miscellaneous information, 469 
iostat — report I/O statistics, 541 

J 

jobs — display job list — csh, 67 
join — relational database operator, 166 


K 

keep mail environment variable, 201 
keepsave mail environment variable, 201 
kgmon — dump profile buffers, 542 
kill — terminate process, 167 
kill — kill jobs and processes — csh, 67 

L 

language 

vgrind — make formatted C listings, 384 
languages 

cc — C compiler, 27 
epp — C preprocessor, 53 
f 77 — FORTRAN compiler, 117 
indent — format C source, 161 
lex — generate lexical analyzer, 173 
lint — C program verifier, 174 
mkstr — create C error messages, 214 
pc — Pascal compiler, 228, 234, 236 
pmerge — merge Pascal files, 238 
px — interpret Pascal, 253 
pxp — generate Pascal execution profile, 254 
pxref — cross reference Pascal program, 256 
rat for — rational FORTRAN, 261 
tcov — code coverage tool, 343 
xstr — extract strings from C code, 407 
last — list last logins, 168 
lastcomm — display last commands, 169 
Id — link editor, 170 
leave — remind you of leaving time, 172 
lex — generate lexical analyzer, 173 
library 

find ordering for object — lorder, 181 
library management 

ar — library maintenance, 9 
ranlib — make random library, 258 
limit — alter resource limitations — csh, 67 
line printer control — lpc, 543 thru 544 
line printer daemon — lpd, 545 
lines 

find, in sorted file — look, 179 
lines in file 

count — wc, 397 
link editor — Id, 170 
lint — C program verifier, 174 
list mail command, 196 
LISTER mail environment variable, 201 
literature references 

find and insert — refer, 263 
load frame buffer image — screenload, 285 
locate program — whereis, 400 
lockscreen — save window context, 177 
login 

change password — pas s wd, 227 
display effective user name — whoami, 403 
listlast — last, 168 
make script of session — script, 287 
rusers — who is on local network, 275 
rwho — who is on local network, 277 
save window context — lockscreen, 177 
to remote machine — r login, 265 
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login, continued 

what are users doing — w, 394 
who — who is logged in, 402 
login accounting — ac, 490 
login — sign on, 178, 299 
login environment 

display variables — printenv, 241 
tset — set terminal characteristics, 362 
tty — get terminal name, 368 
login password 

change in yellow pages — yppas swd, 413 
login — login new user — csh, 67 
logout — end session — csh, 67 
look — find lines in a sorted file, 179 
look for pattern in file, 150 
lookbib — find bibliographic references, 180 
lorder — find ordering for object library, 181 
lpc — line printer control, 543 
lpd — line printer daemon, 545 
lpq — display printer queue, 182 
lpr — print files, 184 
lprm — remove print jobs, 187 
Is — list files, 189 

M 

~m mail tilde escape, 199 
m4 — macro processor, 191 
macro processor — m4, 191 
magnetic tape 

backspace files — mt, 218 
backspace records — mt, 218 
erase — mt, 218 
forward space files — mt, 218 
forward space records — mt, 218 
get unit status — mt, 218 
manipulate — mt,218 
place unit off-line — mt, 218 
retension — mt, 218 
rewind — mt, 218 
skip backward files — mt,218 
skip backward records — mt, 218 
skip forward files — mt,218 
skip forward records — mt, 218 
write EOF mark on — mt,218 
magnify raster image — rastrepl, 260 
mail 

comsat — biff server, 500 
enroll for secret — enroll, 406 
print waiting — prma i 1, 242 
receive secret mail — enroll, 406 
send secret mail — xsend, 406 
mail aliases 

create database — newaliases, 564 
mail — send and receive mail, 193 thru 202 
mail commands, 194 thru 198 
! , 195 
#, 195 
=, 195 
?, 195 
1,197 

alias, 195, 196 


mail commands, continued 
alternates, 195 
cd, 195 
ohdir, 195 
copy, 195 

Copy, 195 
delete, 195 
discard, 195, 196 
dp, 195 
dt, 195 
echo, 195 
edit, 195 
else, 196 
endif, 196 
exit, 195, 198 
file, 195 
folder, 195 
folders, 196 
followup, 196 
Followup, 196 
from, 196 
group, 195, 196 
headers, 196 
help, 196 
hold, 196, 197 
if, 196 

ignore, 195, 196 
list, 196 
mail, 196 
mbox, 196 
next, 196 
pipe, 197 

preserve, 196, 197 
print, 197, 198 
Print, 197, 198 
quit, 197 
reply, 197 
Reply, 197 
Replyall, 197 
replysender, 197 
respond, 197 
Respond, 197 
save, 197 
Save, 197 
set, 197 
shell, 198 
size, 198 
source, 198 
top, 198 
touch, 198 
type, 197, 198 
Type, 197, 198 
undelete, 198 
unset, 198 
version, 198 
visual, 198 
write, 198 
xit, 195, 198 
z, 198 

mail delivery — sendmail, 606 

mail environment variables, 199 thru 202 
allnet, 200 
alwaysignore, 200 
append, 200 
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mail environment variables, continued 

askcc, 200 
ask sub, 200 
autoprint, 200 
bang, 200 
cmd, 200 
conv, 200 
crt, 200 
DEAD, 200 
debug, 200 
dot, 200 
EDITOR, 200 
escape, 200 
folder, 200 
header, 200 
hold, 200 
HOME, 199 
ignore, 200 
ignoreeof, 200 
keep, 201 
keepsave, 201 
LISTER, 201 
MAILRC, 199 
MBOX, 201 
metoo, 201 
no, 201 
onehop, 201 
outfolder, 201 
page, 201 
PAGER, 201 
prompt, 201 
quiet, 201 
record, 201 
replyall, 201 
save, 201 i 
sendmail, 201 
sendwait, 201 
SHELL, 201 
showto, 201 
sign, 201 
Sign, 202 
toplines, 202 
verbose, 202 
VISUAL, 202 
mail mail command, 196 
MAIL shell parameter — sh, 296 
mail services 

biff — mail notifier, 20 
binmail — version 7 mail, 21 
who is mail from, 130 
mail tilde escapes, 198 thru 199 
'1,198 
198 
198 
'<, 199 
' ?, 199 
198 
' | , 199 
-A, 199 
-a, 199 
-b, 199 
-c, 199 
"d, 199 


mail tilde escapes, continued 
-e, 199 
-f, 199 
'h, 199 
~i, 199 
'm, 199 
-p, 199 
'q, 199 
'r, 199 
-s, 199 
-t, 199 
-v, 199 
-w, 199 
-x, 199 

mailaddr — mail addressing, 476 
MAI LCHECK shell parameter — sh, 296 
MAILPATH shell parameter — sh, 296 
MAILRC mail environment variable, 199 
maintain programs — make, 206 thru 210 
maintenance and operation, 487 
make 

delta, 88 
SCCS delta, 88 

make — build programs, 206 thru 210 
make directory — mkdir, 213 
make file system — mkfs, 550 
make font width table — vwidth, 393 
make formatted C listings — vgrind, 384 
make mail aliases database — newaliases, 564 
make new file system — newf s, 565 
make permuted index — ptx, 251 
make prototype file system — mkproto, 552 
make random library — ranlib, 258 
make script of terminal session — s cr ipt, 287 
make special file — mknod,551 
make system configuration files — conf ig, 501 
make system log entry — sys log, 335 
make system special files — makedev, 548 
make yellow pages database — ypinit, 633 
make yellow pages dbm file — makedbm, 547 
makedbm — make yellow pages dbm file, 547 
makedev — make system special files, 548 
makekey — generate encryption key, 549 
man — display online manuals, 21 1 
man — macros to format manual pages, 479 
manipulate magnetic tape — mt, 218 
manipulate routing tables — route, 592 
manual pages — catman — create cat files for, 497 
describe command — what is, 399 
manuals 

display online — man, 211 
mbox mail command, 196 
MBOX mail environment variable, 201 
me — macro package, 481 
memory diagnostic — imemtest, 537 
memory diagnostics — sysdiag, 618 
merge or sort files — sort, 309 
merge Pascal files — pmerge, 238 
mesg — permit or deny messages, 212 
messages 
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messages, continued 

permit or deny — mesg, 212 
metoo mail environment variable, 201 
mi lie — Mille Bomes game, 443 
miscellaneous information, 469 
mkdir — make directory, 213 
mkf s — make file system, 550 
mknod — make special file, 551 
mkproto — make prototype file system, 552 
mkstr — create C error messages, 214 
modes 

chmod — change mode, 35 
monitor program, 553 
monop — Monopoly game, 446 
more — browse text file, 215 
mount — mount file system, 557 
mount file system — mount, 557 
mountd — NFS mount server, 559 
move directory — mv, 219 
movefile — mv, 219 
move print jobs — lpc, 543 
ms — macro package, 483 
mt — manipulate magnetic tape, 218 
multiple columns 

print in — pr, 239 

mv — move or rename files or directory, 219 

N 

ncheck — convert i-numbers to filenames, 560 
nd — network disk control, 561 
neqn — mathematical typesetting, 107 
nets tat — display network status, 562 
network 

copy files across — rep, 262 
rusers — who is logged in on local network, 275 
rwall — write to all users, 276 
rwho — who is logged in on local network, 277 
network debugging — ping, 569 
network disk control — nd, 561 
network file system 
biod daemon, 566 
nfsd daemon, 566 
network interface parameters 

configure — if conf ig, 536 
network routing daemon — routed, 593 
network rwall server — rwal Id, 600 
network status 

display — netstat, 562 
newaliases — make mail aliases database, 564 
newf s — make new file system, 565 
news articles 

receive unprocessed, 581 
remove outdated — expire, 522 
news delivery — sendnews, 609 
next mail command, 196 
NFS mount server — mountd, 559 
NFS statistics 

display — nfsstat, 567 
nfsd daemon, 566 


nfsstat — display network statistics, 567 

NIC host tables 

get from host — gettable, 529 
nice — change priority of command, 220 
nice — run low priority process — esh, 67 
nm — display name list, 221 
no mail environment variable, 201 
nohup — run command immune to hangup, 220 
nohup — run command immune to hangups — esh, 68 
non-builtin command execution 
in C-Shell, 73 

notify — request immediate notification — esh, 68 
nroff 

checknr — check nroff/troff files, 33 
col — filter reverse paper motions, 44 
eolert command, 45 
remove constructs, 90 
nroff — document formatter, 222 
number — convert Arabic numerals to English, 448 

o 

object code management 

ar — library maintenance, 9 
ranlib — make random library, 258 
object file 

find printable strings in — strings, 315 
size — find object file size, 306 
strip — strip symbols and relocation bits, 316 
object library 

find ordering for — lorder, 181 
octal dump file — od, 224 
od — dump file, 224 
onehop mail environment variable, 201 
onintr — handle interrupts in scripts — esh, 68 
online manuals 

display — man, 211 

out folder mail environment variable, 201 
owner of file 

chown — change, 498 

P 

~p mail tilde escape, 199 

pac — printer/plotter accounting, 568 

page — browse text file, 215 

page mail environment variable, 201 

PAGER mail environment variable, 201 

paging devices, specify — swapon, 616 

parameters to Bourne Shell, 295 thru 296 

parser generator — yacc, 408 

Pascal compiler — pc, 228 

Pascal interpreter code translator — pc, 234 

Pascal language 

pmerge — merge Pascal files, 238 
px — interpret Pascal, 253 
pxp — generate Pascal execution profile, 254 
pxref — cross reference Pascal program, 256 
Pascal programming language 
ctags — create tags file, 76 
Pascal translator and interpreter — pc, 236 
passwd — change login password, 227 
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password 

change in yellow pages — yppas swd, 413 
change login — passwd,227 
password file 

edit — vipw, 630 
PATH shell parameter — sh, 296 
patterns 

search in file for, 150 
pc — Pascal compiler, 228 
perf meter — display performance statistics, 231 
perf mon — display performance statistics, 233 
performance monitoring — perf meter, 231, 233 
prof — display program profile, 243 
pxp — generate Pascal execution profile, 254 
time — time command, 350 
performance tools 

display call-graph profile data, 146 
peripheral diagnostics — sysdiag, 618 
permissions 

chmod — change mode, 35 
permit messages — mesg, 212 
permuted index 

generate — ptx, 251 
pi — Pascal interpreter code translator, 234 
ping — debug network, 569 
pipe mail command, 197 
pix — Pascal translator and interpreter, 236 
place magnetic tape unit off-line — mt, 218 
plot — graphics filters, 237 
plot on Versatec — vplot, 388 
pmerge — merge Pascal files, 238 
popd — pop shell directory stack — csh, 68 
portmap — DARPA to RPC mapper, 570 
postmortem crash analyzer — analyze, 495 
pr — prepare files for printing, 239 
predefined variables 

in C-Shell, 70 thru 73 
prepare files for printing — pr, 239 
preserve mail command, 196, 197 
pretty printer 

indent — format C source, 161 
vgrind — make formatted C listings, 384 
preview documents 

colcrt command, 45 

print 

FORTRAN file, 129 

print bibliographic database — rof fbib, 270 
print files 

lpr — print files, 184 
print mail command, 197, 198 
print values from YP database — ypcat, 410 
print waiting mail — prmail, 242 
print working directory name — pwd, 252 
Print mail command, 197, 198 
printenv — display environnment, 241 
printer 

abort — lpc, 543 
clean queue — lpc, 543 
disable queue — lpc, 543 
lpq — display queue, 182 


printer, continued 

enable queue — lpc, 543 

move jobs — lpc, 544 

remove jobs from queue — lprm, 187 

restart — lpc, 543 

start — lpc, 543 

status of — lpc, 543 

stop — lpc, 543 

printer control — lpc, 543 thru 544 
printer daemon — lpd, 545 
printer/plotter accounting, 568 
prmail — print waiting mail, 242 
process 

change priority — renice, 582 
display status — ps, 247 
terminate — kill, 167 
wait — wait process completion, 395 
processes 

get core image of, 137 
prof — display program profile, 243 
profile 

display call-graph, 146 
profiling 

prof — display program profile, 243 
pxp — generate Pascal execution profile, 254 
programming languages 

analyze and disperse compiler error messages, 109 
assembler, 11 
cc — C compiler, 27 
cpp — C preprocessor, 53 
f 77 — FORTRAN compiler, 117 
lex — generate lexical analyzer, 173 
lint — C program verifier, 174 
pc — Pascal compiler, 228, 234, 236 
pmerge — merge Pascal files, 238 
print FORTRAN file, 129 
px — interpret Pascal, 253 
pxp — generate Pascal execution profile, 254 
pxref — cross reference Pascal program, 256 
split FORTRAN file, 131 
vgrind — make formatted C listings, 384 
xstr — extract strings from C code, 407 
programming tools 

adb — debug tool, 2 

be — calculator language, 18 

cb — C beautifier, 26 

compiler generator, 116 

ctags — create tags file, 76 

dbxtool — debugger, 80 

display call-graph profile data, 146 

indent — format C source, 161 

install — install files, 165 

Id — link editor, 170 

lex — generate lexical analyzer, 173 

lint — C program verifier, 174 

lorder — find ordering for object library, 181 

m4 — macro processor, 191 

maintain object libraries, 9 

make — build programs, 206 thru 210 

mkstr — create C error messages, 214 

nm — display name list, 221 

prof — display program profile, 243 

ranlib — make random library, 258 
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programming tools, continued 

ratf or — rational FORTRAN, 261 
sees — source code control, 279 
size — find object file size, 306 
strings — find printable strings in binary file, 315 
strip — strip symbols and relocation bits, 316 
tcov — code coverage tool, 343 
time — time command, 350 
touch — update last modified date of file, 356 
yacc — compiler generator, 408 
programs 

introduction, 1 

PROM monitor program, 553 

prompt mail environment variable, 201 

provide truth values — true, 361 

prs — display SCCS history, 244 

ps — display process status, 247 

PS1 shell parameter — sh, 296 

PS2 shell parameter — sh, 296 

pstat — display system statistics, 571 

pti — (old) troff interpreter, 250 

ptx — generate permuted index, 251 

purge directory — rmdir, 269 

purge file or directory — rm,267 

pushd — push shell directory stack — esh, 68 

pwd — print working directory name, 252, 299 

px — interpret Pascal, 253 

pxp — generate Pascal execution profile, 254 

pxref — cross reference Pascal program, 256 

Q 

~q mail tilde escape, 199 
queue 

lpq — display printer, 1 82 
remove jobs from printer — lprm, 187 
quiet mail environment variable, 201 
quit mail command, 197 
quiz — test knowledge, 449 
quot — su mm arize file system ownership, 575 

R 

“r mail tilde escape, 199 

rain — display raindrops, 450 

ranlib — make random library, 258 

rastrepl — magnify raster image, 260 

ratf or — rational FORTRAN, 261 

rc — startup commands, 578 

rep — remote file copy, 262 

rdate — remote date, 579 

read shell command — sh, 299 

read mail — mail, 193 thru 202 

readonly shell command — sh, 299 

reboot — system startup procedures, 580 

reboot system — f astboot, 523 

rebuild yellow pages database — ypmake, 634 

receive secret mail — enroll, 406 

receive unprocessed news articles — recnews, 581 

recnews — receive unprocessed news articles, 581 

record mail environment variable, 201 


refer — insert literature references, 263 
regenerate programs — make, 206 thru 210 
rehash — recompute co mm and hash table — esh, 68 
relational database operator — join, 166 
reminder services 

biff — mail notifier, 20 
calendar — reminder service, 24 
leave — remind you of leaving time, 172 
remote execution server — rexecd, 587 
remote file copy — rep, 262 
remote host 

send file to — uusend, 378 
remote login — rlogin, 265 
remote login server — rlogind, 589 
remote magtape protocol server — rmt, 591 
remote procedure call services 
sprayd — spray server, 614 
remote shell — rsh, 271 
remote shell server — r shd, 597 
remote system cu 

connect to — cu, 351 
remote system tip 

connect to — tip, 351 
remove 

columns from file, 46 
delta — rmdel, 268 
filename affixes, 17 
nroff, troff, tbl and eqn constructs, 90 
remove delta from SCCS file — rmdel, 268 
remove directory — rmdir, 269 
remove file or directory — rm, 267 
remove outdated news articles — expire, 522 
remove print jobs — lprm, 187 
remove repeated lines — uniq, 371 
rename directory — mv, 219 
rename file — mv, 219 
renice — change process priority, 582 
repeat — execute command repeatedly — esh, 68 
reply mail command, 197 
Reply mail command, 197 
replyall mail environment variable, 201 
Replyall mail command, 197 
replysender mail command, 197 
reset — reset terminal bits, 362 
reset terminal bits — reset, 362 
respond mail command, 197 
Respond mail command, 197 
restart printer — lpc, 543 
restore — restore file system, 584 
restore file system — restore, 584 
restore frame buffer image — screenload, 285 
retension magnetic tape — mt, 218 
return shell command — sh, 299 
rev — reverse lines in file, 264 
reverse lines in file — rev, 264 
rewind magnetic tape — mt, 218 
rexecd — remote execution server, 587 
rlogin — remote login, 265 
rlogind — remote login server, 589 
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rm — remove file or directory, 267 
rmail — process remote mail, 590 
rmdel — remove delta from SCCS file, 268 
rmdir — remove directory, 269 
rmt — remote magtape protocol server, 591 
rof f bib — print bibliographic database, 270 
route — manipulate routing tables, 592 
routed — network routing daemon, 593 
routing tables 

manipulate — route, 592 
rpcinf o — report RPC information, 595 
rsh — remote shell, 271 
rshd — remote shell server, 597 
rstatd — kernel statistics server, 599 
rup — display status of local hosts, 273 
ruptime — display status of local hosts, 274 
rusers — who is logged in on local network, 275 
rwalld — network rwall server, 600 
rwho — who is logged in on local network, 277 
rwhod — system status server, 601 

s 

' s mail tilde escape, 199 
sa — accounting summary, 603 
sail — wooden ships and iron men, 452 
Save mail command, 197 
save mail environment variable, 201 
savecore — save OS core dump, 605 
sees — source code control system, 279 
SCCS commands 

admin — administer SCCS, 6 
ede — change delta commentary, 31 
comb — combine deltas, 47 
get — get SCCS file, 138 
help — get SCCS help, 155 
ede — display SCCS history, 244 
rmdel — remove delta, 268 
sact — display SCCS file editing status, 278 
sccsdif f — compare versions of SCCS file, 283 
unget — unget SCCS file, 370 
val — validate SCCS file, 381 
SCCS delta 

change commentary, 31 
combine, 47 
create, 88 

remove — rmdel, 268 
SCCS history 
display, 244 

sccsdif f — compare versions of SCCS file, 283 
screen fonts 
edit, 126 

screen-oriented editor — vi, 386 

screendump — dump frame buffer image, 284 

screenload — restore frame buffer image, 285 

script — make script of terminal session, 287 

search for files, 122 

search for pattern in file, 150 

secret mail 

enroll for — enroll, 406 
receive — enroll, 406 


secret mail, continued 
send — xsend, 406 
sed — stream editor, 288 
send and receive mail — mail, 193 thru 202 
send file to remote host — uusend, 378 
send secret mail — xsend, 406 
sendmail — mail delivery system, 606 
sendmail mail environment variable, 201 
sendnews — news delivery, 609 
sendwait mail environment variable, 201 
servers 

comsat — biff server, 500 
f tpd — Internet File Transfer Protocol, 527 
inetd — internet services daemon, 538 
mountd — mount request server, 559 
rexecd — remote execution server, 587 
rlogind — remote login server, 589 
rshd — remote shell server, 597 
rstatd — kernel statistics server, 599 
rwalld — network rwall server, 600 
rwhod — system status server, 601 
talkd — talk program server, 621 
telnetd — TELNET protocol server, 622 
tf tpd — Trivial File Transfer Protocol server, 623 
timed — DARPA Time server, 624 
yppas swdd — yellow pages password server, 635 
set 

current domain, 97 
current host name, 157 
name of current host, 157 
set shell command — sh, 299 thru 300 
set mail command, 197 

set — change value of shell variable — esh, 68 

set terminal characteristics — tset, 362 

set terminal options — stty, 317 

setenv — set variable in environment — esh, 69 

sh — Bourne Shell, 294 thru 301 

Shell 

Bourne — sh, 294 thru 301 

shell 

change login, 36 
chsh — change shell, 36 
esh — C shell, 57 thru 75 
remote — rsh, 271 

Shell commands (Bourne Shell), 294 thru 295, 298 thru 300, see 
also Bourne Shell commands 
Shell functions (Bourne Shell), 295 
shell mail command, 198 
SHELL mail environment variable, 201 
SHELL shell parameter — sh, 296 
Shell parameters (Boume Shell), 295 thru 296 
Shell scripts 

sun — test for Sun Workstation, 323 
true — provide truth values, 361 
vax — test machine is VAX, 382 
shells 

false command, 120 
shift shell command — sh, 300 
shift — shift argument list — esh, 69 
showmount — display remote mounts, 610 
showto mail environment variable, 201 
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shutdown — shutdown system, 611 
sign mail environment variable, 201 
login — sign on, 178 

to remote machine — rlogin, 265 
Sign mail environment variable, 202 
signal handling 
in C-Shell, 74 
signon 

signon last — last, 168 
size — find object file size, 306 
size mail command, 198 
skip backward magnetic tape files — mt, 218 
skip backward magnetic tape records — mt, 218 
skip forward magnetic tape files — mt, 218 
skip forward magnetic tape records — mt, 218 
skyversion — display SKY version, 612 
sleep — suspend execution, 307 
smoothing 

spline — interpolate smooth curve, 313 
snake — display chase game, 462 
soelim — eliminate .so’s from nroff input, 308 
sort bibliographic database — sortbib, 311 
sort — sort or merge files, 309 
sort or merge files — sort, 309 
sort topologically — tsort, 367 
sortbib — sort bibliographic database, 311 
sorted file 

find lines in — look, 179 
remove repeated lines — uniq, 371 
source code control system — sees, 279 
source mail command, 198 
source — read commands from file — esh, 69 
spaces 

unexpand to tabs, 1 13 

special characters for equations — eqnchar, 471 
special file 

make — mknod, 551 
special files — makedev, 548 
spell — check spelling, 312 
spellin — check spelling, 312 
spellout — check spelling, 312 
spline — interpolate smooth curve, 313 
split — split file into pieces, 314 
spray — spray packets, 613 
sprayd — spray server, 614 
stand-alone utilities 

diag — initialize/diagnose disk, 510 
gxtest — graphics board diagnostics, 532 
imemtest — memory diagnostic, 537 
standard output 

copy to many files — tee, 344 
start printer — lpc, 543 
startup procedures — reboot, 580 
statistics 

I/O — iostat, 541 
rstatd — kernel statistics server, 599 
statistics of NFS 

display — nfsstat, 567 
status of network 


status of network, continued 
display — netstat, 562 
status of printer — lpc, 543 
sticky — set sticky bit, 615 
stop printer — lpc, 543 
stop processor — halt, 533 
stop — halt job or process — esh, 69 
stream editor — sed, 288 

strings — find printable strings in binary file, 315 
strip 

filename affixes, 17 

strip — strip symbols and relocation bits, 316 

stty — get terminal options, 317 

stty — set terminal options, 317 

stty_from_defaults command, 320 

su — substitute user id, 321 

substitute user id — su, 321 

sum — sum and count blocks in file, 322 

sun — test for Sun Workstation, 323 

Sun Workstation 

test for — sun, 323 
suntools, 324 

suntools — Suntools window environment, 324 
SunView 

start up environment, 324 
SunWindows 

graphics tool, 144 
icon edit, 158 

suspend execution — sleep, 307 
suspend — suspend shell — esh, 69 
swapon — specify paging device, 616 
swapping devices, specify — swapon, 616 
switch — multi-way branch — esh, 69 
symbolic link 

make — In, 176 

sync — update super block, 334, 617 
sysdiag — system diagnostics, 618 
syslog — make system log entry, 335, 619 
system administration 

adduser — add new user account, 493 
analyze — crash analyzer, 495 
catman — create cat files for manual, 497 
install — install files, 165 
system configuration files 
build — config, 501 
system maintenance and operation, 487 
system PROM monitor program, 553 
system special files — makedev, 548 
system status server — rwhod, 601 

T 

~t mail tilde escape, 199 
tabs 

expand to spaces, 1 13 
tail — display last part of file, 336 
talk — talk to another user, 337 
talkd — talk server, 621 
tape 

backspace files — mt,218 
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tape, continued 

backspace records — mt, 218 
erase — mt, 218 
forward space files — mt, 218 
forward space records — mt, 218 
get unit status — mt, 218 
manipulate magnetic — mt, 218 
place unit off-line — mt, 218 
retension — mt,218 
rewind — mt, 218 
skip backward files — mt,218 
skip backward records — mt, 218 
skip forward files — mt, 218 
skip forward records — mt, 218 
write EOF mark on — mt, 218 
tape archiver — tar, 338 
tar — tape archiver, 338 
tbl 

remove constructs, 90 
tbl — table formatter, 342 
tcov — code coverage tool, 343 
tee — copy standard output to many files, 344 
tektool — emulate Tektronix 4014, 345 
Tektronix 4014 

emulate — tektool, 345 
telnet — TELNET interface, 347 
telnetd — TELNET protocol server, 622 
terminal 

get name of — tty, 368 
get options — stty, 317 
make script of session — script, 287 
reset bits — reset, 362 
set characteristics — tset, 362 
set options — stty, 317 
test shell command — sh, 300, 348 
test for Sun Workstation — sun, 323 
test machine is VAX — vax, 382 
text editing 

ed — line editor, 100 
edit — line editor, 111 
ex — line editor, 111 
sed — stream editor, 288 
text editor 

vi — visual editor, 386 
text file 

browse through — more, 215 
browse through — page, 215 
text processing 

awk — scan and process patterns, 14 
cat — concatenate files, 25 
search for patterns, 150 
text processing utilities 

reverse lines in file — rev, 264 
sort — sort or merge files, 309 
spell — check spelling, 312 
split — split file into pieces, 314 
tail — display last part of file, 336 
tr — translate characters, 357 
tsort — topological sort, 367 
ul — underline text, 369 
uniq — remove repeated lines, 371 
tf tp — trivial file transfer program, 349 


tftpd — Trivial File Transfer Protocol server, 623 
then shell co mm and — sh, 294 

tilde escapes in mail, 198 thru 199, see also mail tilde escapes 
time 

display date and, 77 
display in window, 40 
time — time command, 350 
time — time command — csh, 69 
timed — time server, 624 
timed event services 

at — do job at specified time, 13 
calendar — reminder service, 24 
leave — remind you of leaving time, 172 * 
timed events — cron, 508 
times shell command — sh, 300 
tip — connect to remote system, 351 
top mail command, 198 
toplines mail environment variable, 202 
topological sort — t sort, 367 
touch — update last modified date of file, 356 
touch mail command, 198 
tr — translate characters, 357 
translate and interpret Pascal programs — pc, 236 
translate characters — tr, 357 
transliterate protocol trace — trpt, 625 
trap shell command — sh, 300 
trek — Star Trek game, 464 
trivial file transfer program — tftp, 349 
troff 

checknr — check nroff/troff files, 33 
col — filter reverse paper motions, 44 
colcrt command, 45 
remove constructs, 90 
troff — typeset documents, 359 
trpt — transliterate protocol trace, 625 
true — provide truth values, 361 
tset — set terminal characteristics, 362 
tsort — topological sort, 367 
tty — get terminal name, 368 
tune file system — tunefs, 626 
tunef s — tune file system, 626 
type shell command — sh, 300 
type mail command, 197, 198 
Type mail command, 197, 198 
typeset documents — troff, 359 

u 

ul — underline text, 369 

umask shell command — sh, 300 

umask — change/display file creation mask — csh, 69 

umount — unmount file system, 557 

unalias — remove aliases — csh, 70 

uncompress — uncompress files, 49 

uncompress files, 49 

undelete mail command, 198 

underline text — ul,369 

unexpand — spaces to tabs, 1 13 

unget — unget SCCS file, 370 

unhash — discard hash table — csh, 70 
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uniq — remove repeated lines, 371 

units — convert units, 372 

UNIX to UNIX co mm and execution — uux, 379 

UNIX to UNIX copy — uucp, 375 

unlimit — remove resource limitiations — csh, 70 

unmount file system — umount, 557 

unset shell command — sh, 300 

unset mail command, 198 

unset — discard shell variables - csh, 70 

unsetenv — remove environment variables — csh, 70 

until shell co mm and — sh, 294 

update — update super block, 627 

update last modified date of file — touch, 356 

update programs — make, 206 thru 210 

update super block — sync, 334 

uptime — display system up time, 373 

user 

display effective name — whoami, 403 
talk to another — talk, 337 
write to another — write, 404 
userid 

substitute — su, 321 

users 

list last logins — last, 168 
what are they doing — w, 394 
who — who is logged in, 402 
write to all — wall, 396 
users — display users on system, 374 
utilities 

introduction, 1 

uuclean — clean UUCP spool area, 628 
UUCP 

clean spool area — uuclean, 628 
uucp — UNIX to UNIX copy, 375 
UUCP log— uulog, 375 
uudecode — decode binary file, 377 
uuencode — encode binary file, 377 
uulog — UUCP log, 375 
uurec — receive news articles, 629 
uusend — send file to remote host, 378 
uux — UNIX to UNIX command execution, 379 

V 

~v mail tilde escape, 199 
val — validate SCCS file, 381 
validate SCCS file — val, 381 
variable substitution 

in C-Shell, 60 thru 62 
variables in C Shell, 70 thru 73 
vax — test machine is VAX, 382 
verbose mail environment variable, 202 
verification tools 

lint — C program verifier, 174 
plot graphics on — vplot, 388 
version 

identify, of file — what, 398 
version mail command, 198 
vf ontinf o — examine font files, 383 
vgrind — make formatted C listings, 384 


vi — visual editor, 386 

view — view file, 387 

vipw — edit password file, 630 

visual editor — vi, 386 

visual mail command, 198 

VISUAL mail environment variable, 202 

vmstat — display virtual memory statistics, 631 

vplot — plot on Versatec, 388 

vpq — display raster print queue, 389 

vpr — print on raster printer/plotter, 389 

vprint — print on raster printer/plotter, 389 

vprm — remove jobs from raster print queue, 389 

vswap — convert foreign font files, 391 

vtrof f — format document for raster printer, 392 

vwidth — make font width table, 393 

w 

w — what are users doing, 394 

~w mail tilde escape, 199 

wait shell co mm and — sh, 300, 395 

wait — wait for background process — csh, 70 

wall — write to all users, 396 

wc — count lines, words, characters in file, 397 

what are users doing — w, 394 

what — identify file version, 398 

whati s — describe command, 399 

whereis — find program, 400 

which — find program file, 401 

while shell command — sh, 294 

while — repeat commands — c sh, 70 

who — who is logged in, 402 

who is logged in on local network — ruser s, 275, 277 
whoami — display effective user name, 403 
window 

save context — lockscreen, 177 
window environment, 320, 324 
window management 

adjacentscreens command, 5 
words in file 

count — wc, 397 
working directory 

cd — change directory, 30 
display name of — pwd, 252 
worm — growing worm game, 466 
worms — animate worms on display, 467 
write — write to another user, 404 
write EOF mark on magnetic tape — mt, 218 
write mail command, 198 
write to all users — wall, 396 
write to all users on network — rwall, 276 
wump — hunt the Wumpus game, 468 

X 

~x mail tilde escape, 199 
xget — receive secret mail, 406 
xit mail command, 195, 198 
xsend — send secret mail, 406 
xstr — extract strings from C code, 407 


) 
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Y 

yacc — compiler generator, 408 
yellow pages 

change login password in — yppa s swd, 413 
make database — ypinit, 633 
make dbm file — makedbm, 547 
print values from database — ypcat, 410 
rebuild database — ypmake, 634 
yes — be repetitively affirmative, 409 
ypcat — print values from YP database, 410 
ypinit — * make yellow pages database, 633 
ypmake — rebuild yellow pages database, 634 
yppasswd — change login password in yellow pages, 413 
ypserv — yellow pages server process, 638 
ypwhich — who is yellow pages server, 412, 641 
yppasswdd — yellow pages password server, 635 


z 

z mail command, 198 
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